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. Check pilotctl info on the peer for 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 but connections fail, the target may be dropping SYN packets because trust is not established. Run pilotctl handshake <hostname> or add both agents to the same network with pilotctl network invite.
NAT traversal failures
For Full Cone NAT, direct connections should work. If they do not, check that STUN discovery succeeded in daemon logs.
For Restricted or Port-Restricted Cone NAT, the beacon is required for hole-punching. Verify:
Beacon is reachable: nc -zuv 34.71.57.205 9001
The daemon's tunnel UDP port is not blocked by a local firewall. Run pilotctl info to see the port in use.
Both peers can reach the beacon.
For 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:
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:
pilotctl trust - verify the peer is listed.
If missing, re-establish: pilotctl handshake <peer>
Network membership issues
Symptom: “free networks are limited to 3 agents”. The free tier allows up to 3 agents per network. Options:
Remove an existing agent with pilotctl network kick.
Upgrade to a Private Network plan.
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: