Troubleshoot a Fleet Node

Start with the installed version, systemd service, and recent logs:

cat /opt/fleetnode/version.txt
sudo systemctl status fleet-node.service --no-pager
sudo journalctl -u fleet-node.service -n 200 --no-pager

To inspect the stored connection without printing credentials:

sudo runuser -u fleetnode -- \
  /opt/fleetnode/fleetnode --state-dir /var/lib/fleetnode status

The status command prints the Fleet server URL, node ID, identity fingerprint, whether an API key and session token are present, and the session expiry. It does not print the credentials.

Read the status in Fleet

Open Settings → Nodes.

Resume an interrupted enrollment

Run the same command shown by Settings → Nodes → Enroll node:

sudo fleetnode-enroll --server-url=https://fleet.example.com/api-proxy

If the host registered but did not receive its API key, the helper resumes the authentication prompt. In Fleet, use Confirm enrollment for the waiting node, compare the fingerprint, and paste the new API key into the host prompt.

If the one-time enrollment code expired before registration, close the enrollment window and start again to create a new code.

The node is stale or never connected

1. Check fleet-node.service and its recent logs.
2. Confirm that the Fleet Node host can resolve and reach the stored server_url.
3. Confirm that the host clock is correct. Authentication challenges expire.
4. Confirm that the node has not been revoked in Fleet.
5. If Fleet uses a private certificate authority, confirm that the Fleet Node host trusts it.

Restart the service after correcting the problem:

sudo systemctl restart fleet-node.service

The certificate is not trusted

Fleet Node verifies HTTPS certificates with the host’s trust store. Install the certificate authority that issued Fleet’s certificate, then restart the service.

For a high-availability Fleet deployment, first compare the public service CA fingerprint with the authenticated installer output. Then install the verified certificate on a Debian-based Fleet Node host:

sudo install -m 0644 proto-fleet-ha-service-ca.crt \
  /usr/local/share/ca-certificates/proto-fleet-ha-service-ca.crt
sudo update-ca-certificates
sudo systemctl restart fleet-node.service

Do not use --allow-insecure-transport to bypass an HTTPS certificate problem. That option permits HTTP for testing; it does not turn off HTTPS certificate verification.

Miners are not discovered

Confirm that the Fleet Node host can route to each scan target and reach the discovery ports listed under supported hardware.

Automatic local discovery chooses a private IPv4 subnet from the host. On a host with multiple network interfaces, set the intended subnet in /etc/fleetnode/fleetnode.env:

sudoedit /etc/fleetnode/fleetnode.env

Add one line with a private IPv4 CIDR:

FLEETNODE_LOCAL_DISCOVERY_SUBNET=10.90.0.0/24

Then restart the node:

sudo systemctl restart fleet-node.service

The subnet must be private and within Fleet’s supported scan-size limit. You can also enter explicit private IP addresses or smaller subnets when starting discovery in Fleet.

Re-enroll with a different Fleet server

Changing the server discards the host’s existing node identity.

1. In the old Fleet deployment, revoke the node under Settings → Nodes.
2. In the new Fleet deployment, start Enroll node and copy its command and one-time code.
3. On the host, run the copied command with --force appended.
4. Compare the new identity fingerprint before confirming the node.

The helper stops the service before replacing local enrollment state.

An update does not complete

• If a download reports a network or checksum problem, the installed service has not been replaced. Confirm outbound HTTPS access and retry the same exact release.
• If a staged install reports a checksum problem, such as checksum sidecar is not bound to, the archive or its .sha256 changed in transit or came from different releases. The installed service has not been replaced. Download both again from the same release, copy them to the host unchanged, and retry.
• If a staged install reports that a release directory or file wasn’t found, confirm the layout <release-dir>/<version>/fleetnode-<version>-linux-<arch>.tar.gz and its .sha256, and pass the release directory rather than the version directory.
• If a staged install rejects a path because it’s a symbolic link, has the wrong owner, or is writable by group or others, fix that path and run the installer as the user who owns the staged files. For example, chmod -R go-w <release-dir> removes group and other write access. If the rejected path is a parent directory you can’t change, stage the files somewhere else. If a parent directory is a symbolic link, pass the real path instead, for example --release-dir "$(realpath "$HOME/fleetnode-releases")".
• If a staged install reports that a path isn’t accessible to the invoking user, give that user read access. For files that root owns, run sudo chmod -R a+rX <release-dir>.
• If the installer reports that the release bundle repository conflicts with the selected source, the archive came from a different repository than the installer. Download both from the same release.
• If it reports that another installer is running, wait for that process to finish before retrying.
• If the service is activating, inspect its logs. The installer will not replace a service during an incomplete start.
• If the candidate cannot start, review both the candidate error and any rollback message. A successful rollback restores and restarts the previous service.

For help interpreting the output, open a GitHub Discussion or report a bug. Do not attach /var/lib/fleetnode/state.yaml, API keys, enrollment codes, or private keys.