Troubleshooting

Playbooks for the problems you are most likely to hit. Each lists the usual causes in the order worth checking.

A device will not come online

1. Connectivity. Confirm outbound TCP 443 to the platform is allowed (directly or via proxy). See Connectivity & ports.
2. Time. A badly wrong clock breaks secure connections and attestation. Ensure the device can reach an NTP source — see Time synchronization.
3. Network configuration. A recent network change may have broken connectivity; the device should fall back to its image network settings unless fallback is disabled. See connection fallback.
4. Onboarding. Confirm the device has valid provisioning credentials or a working onboarding method.

A network change broke connectivity

• If network configuration fallback is enabled, the device should revert to its image network settings after a failed change.
• If fallback is disabled, push a corrected configuration, or recover the device on-site.
• Configure a backup uplink (such as cellular) so a wired/Wi-Fi mistake does not isolate the device — see uplink fallback.

An encrypted device will not unlock

• After a hardware change (motherboard/TPM), automatic unlock no longer matches. Use the recovery passphrase.
• If the recovery passphrase is lost and automatic unlock is unavailable, the device must be re-imaged (encrypted data is not recoverable).

Locked out of SSH

• Your management host may have been banned after failed logins. Add it to the SSH ignore list to prevent this.
• Check the source allow/deny lists — your address may not be permitted.
• Administer the device through remote access while you fix SSH settings.

A USB device is rejected

• USB device control is enabled and the device does not match an allow rule. Add a rule for it, or confirm an existing rule matches its ID, port, or interface.

An OS upgrade did not complete

• Confirm the device can download the new version (connectivity and any proxy).
• A device that fails to start a new version can fall back to the retained previous version; you can also roll back explicitly.

The device is out of storage

• Container images, workload data, and logs share the data area. Check storage usage in device metrics.
• Lower logging severity if logs are consuming space.

A change I made on the device reverted

• The change likely modified the read-only system image. Apply it through configuration instead — see how persistence works and persistent paths.

Next steps

Most of the checks above start with looking at a device. To do that without guessing, and to be told when something breaks rather than discovering it here, continue with Monitoring & alerts.