Help

Troubleshooting

Logs, and what the common errors mean.

Logs

journalctl -u fieldhand -f          # systemd
tail -f /var/log/fieldhand.log      # OpenRC
fieldhand version

Common errors

relay rejected the device key (revoked?)

The device was removed in the dashboard, or the same key was enrolled again elsewhere. Run the install command again.

x509: certificate has expired or is not yet valid

The device clock is wrong. Fix the time (NTP) and the agent reconnects by itself.

dial tcp …: i/o timeout / connection refused

Outbound 443 is blocked. Allow api.fieldhand.dev and relay.fieldhand.dev, or set HTTPS_PROXY.

curl: (60) SSL certificate problem: unable to get local issuer certificate

The device has no CA certificates (common on minimal images). Install them (apt install ca-certificates, apk add ca-certificates) and run the installer again. The agent itself carries its own roots and doesn't need them.

enroll rejected (HTTP 401)

The install token expired (24 hours) or ran out of uses. Create a new one in the dashboard.

enroll rejected (HTTP 402)

The free plan's five devices are in use. Upgrade, or remove a device you no longer need.

downloaded binary does not run on this machine

Usually a 32-bit userland on a 64-bit kernel, or the other way round. Tell us the output of uname -m and file /bin/sh.

The device keeps going offline and online

Check its connection history. "heartbeats stopped" every few minutes means the network drops idle connections faster than the agent has learned; it adapts within a few cycles. Constant "closed by the device" means the agent is restarting: look at its log. Two devices cloned from one enrolled image will knock each other off; see golden image.

The shell opens but ls shows nothing

Root's home directory, /root, is usually empty. Try ls -A or ls /.

Something wrong or missing on this page? Tell us.