Troubleshooting

Playbooks for common device problems, with causes in the order worth checking.

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

Collect a debug bundle

When you need to hand the problem to someone else — or keep a record of a device in its failed state — collect a debug bundle. The cuttle CLI asks the device to gather its logs and system state into an archive, then downloads it:

cuttle devices collect-debug-bundle \
  projects/your-project/regions/us-west2/devices/pi03

The bundle is saved in the current directory under a generated name. Use --filename to choose your own, and -v to follow the collection and download as they happen:

cuttle devices collect-debug-bundle --filename pi03-offline.zip -v \
  projects/your-project/regions/us-west2/devices/pi03

The device has to be reachable through the platform for this to work, so collect the bundle while the problem is visible rather than after a reboot has cleared it. If the device is not reachable at all, the playbooks below are the place to start. The command is not available on Windows.

A device will not come online

Connectivity. Confirm outbound TCP 443 to the platform is allowed (directly or via proxy). See Connectivity & ports.
Time. A badly wrong clock breaks secure connections and attestation. Ensure the device can reach an NTP source — see Time synchronization.
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.
Onboarding. Confirm the device has valid provisioning credentials or a working onboarding method.

If the device plainly has working internet access, go to The device has internet access but still shows offline instead — the causes there all survive a successful ping.

The device has internet access but still shows offline

This is the most commonly misdiagnosed device problem, because the usual test — browsing from the same network, or pinging a public address — passes. General internet access does not prove that SPEKTRA Edge traffic works. The device needs a specific kind of connection, to specific names, with an accurate clock.

Work through these in order; each is a different failure that produces the same “Offline” indicator.

Name resolution. Confirm the device can resolve the platform names, using the resolvers it actually uses on site. Reaching an IP address proves nothing if DNS is filtered or split-horizon. See DNS.
The shape of the allowlist. On equipment that treats * as exactly one label, *.edgelq.com does not match the deeper hostnames a device is given after onboarding, so it connects once and then stops. See Match subdomains at any depth.
TLS inspection. If the network inspects TLS, the device cannot validate the platform certificate and the handshake fails. Destinations must be exempted from inspection — see Proxy configuration.
Proxy method support. The proxy must permit CONNECT to port 443. A proxy that handles only ordinary HTTP methods blocks the device even though browsers on the same network work fine. See What the proxy must allow.
The clock. A clock far enough off breaks certificate validity checks before anything else is attempted. See Time synchronization.
The right platform and region. Confirm the device is pointed at the environment and region that hold your project. A device configured for one and enrolled in the other connects to something, and never appears where you are looking.

A gRPC reflection error does not mean the connection failed

Testing an endpoint with a generic gRPC client often returns an error about server reflection not being supported. That is expected — the platform does not have to expose reflection — and it means your request reached the service. Treat it as evidence that transport works, not as the fault.

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 settings supplied as files.

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.