This document covers common issues and how to fix them.
Daemon won’t start
Symptom: “address already in use”. Another process is holding the tunnel port or the IPC socket. The daemon binds an OS-assigned UDP port by default, or the port passed to --listen.
Check for existing daemon: pilotctl daemon status
Stop it: pilotctl daemon stop
If the socket is stale: rm -f /tmp/pilot.sock
Try again: pilotctl daemon start
Symptom: “invalid email” on startup. If --email is passed with a malformed address, the daemon refuses to start. Email is otherwise optional. Omitting --email causes the daemon to synthesise <fingerprint>@nodes.pilotprotocol.network from the public-key fingerprint.
Symptom: “cannot reach registry” or “connection refused”.
Check the registry address: pilotctl config
Test connectivity: nc -zv 34.71.57.205 9000
Override if needed: export PILOT_REGISTRY=host:9000
Check firewall rules - outbound TCP port 9000 must be open
Connection timeouts
Symptom: connections to peers time out.
Verify the peer is online: pilotctl ping <hostname>
Check that the peer’s tunnel UDP port is reachable. Find the port in the peer’s daemon log (~/.pilot/pilot.log, the “discovered public endpoint” line). The command pilotctl info redacts endpoints and will not show the port.
If both peers are behind NAT, ensure the beacon is reachable on UDP port 9001.
Check for mutual trust or shared network: pilotctl trust
If ping works, trust and the network path are already established; the SYN trust gate applies to every port, including the echo port ping uses. A connection failure on another port means the target service isn't listening there, or a port policy blocks it.
NAT traversal failures
Full Cone NAT: Direct connections should work. If they do not, check that the STUN discovery succeeded, which is visible in daemon logs.
Restricted / Port-Restricted Cone NAT: This requires the beacon for hole-punching. Verify the following:
Beacon is reachable: nc -zuv 34.71.57.205 9001
The daemon’s tunnel UDP port is not blocked by a local firewall. Find the port in ~/.pilot/pilot.log (the “discovered public endpoint” line); pilotctl info redacts it.
Both peers can reach the beacon.
Symmetric NAT: Direct connections are not possible. Pilot automatically falls back to relay through the beacon. If relay fails:
Ensure both peers can reach the beacon on UDP 9001.
Check daemon logs for “relay” messages.
If using a fixed endpoint (--endpoint), verify the address and port are correct.
Trust and handshake issues
Symptom: handshake times out. The target must approve the handshake. Check the following:
Is the target online? pilotctl find <hostname>
Does the target have pending requests? pilotctl pending (on the target)
Auto-approve may be off. The target must run pilotctl approve <node_id>.
Symptom: “connection refused” despite trust. Trust may have been revoked. Check the following:
pilotctl trust - verify the peer is listed
If missing, re-establish: pilotctl handshake <peer>
Network membership issues
Symptom: “network membership limit reached”. The network reached its configured member cap. Options include:
Raise the network policy's member limit: pilotctl network policy <network_id> --max-members <n>.
Remove an existing agent with pilotctl network kick.
Symptom: agents can’t communicate despite being in the same network.
Verify membership: pilotctl network members <network_id>
Check that both agents are online: pilotctl find <hostname>
Test basic connectivity: pilotctl ping <hostname>
If using invite-only, ensure the invite was accepted.
IPC socket errors
Symptom: “daemon is not running” but it is. The IPC socket path may be wrong or stale.
Check the socket: ls -la /tmp/pilot.sock
Remove stale socket: rm -f /tmp/pilot.sock
Restart the daemon: pilotctl daemon stop && pilotctl daemon start
If using a custom socket, set: export PILOT_SOCKET=/path/to/socket
Symptom: “text file busy” when updating binaries. The daemon is still running and holding the binary open.
Stop the daemon: pilotctl daemon stop
Remove old binary: rm -f ~/.pilot/bin/pilot-daemon
Install new version: curl -fsSL https://pilotprotocol.network/install.sh | sh
Encryption key issues
Symptom: “encrypted packet but no key”. Keys can desynchronize after multiple restarts of both peers.
Restart the daemon on both sides.
Re-establish trust: pilotctl untrust <node_id> then pilotctl handshake <hostname>
If in a network, remove and re-add the agents with pilotctl network kick then pilotctl network invite.
General diagnostic steps
When something isn’t working, follow this checklist:
Check daemon status: pilotctl daemon status - is it running?
Check identity: pilotctl info - do you have a node ID and address?
Check registry: pilotctl peers - can you see other nodes?
Check connectivity: pilotctl ping <peer> - can you reach the peer?
Check trust: pilotctl trust - is the peer in your trust list?
Check networks: pilotctl network list - are you in the right network?
Check logs: cat ~/.pilot/pilot.log - look for error messages
Test echo port: pilotctl connect <peer> 7 - the echo server should respond