Another process is holding the tunnel port (the daemon binds an OS-assigned UDP port by default, or the port passed to --listen) or the IPC socket.
Check for an 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
Passing --email with a malformed address makes the daemon refuse to start. Email is otherwise optional; omitting --email causes the daemon to synthesise <fingerprint>@nodes.pilotprotocol.network from the public-key fingerprint.
pilotctl daemon start --email you@example.com
Or set it in ~/.pilot/config.json:
{ "email": "you@example.com" }
Cannot reach the registry
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 exact 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
Full Cone NAT
Direct connections should work. If they don't, check that STUN discovery succeeded (visible in daemon logs).
Restricted / Port-Restricted Cone NAT
Requires the beacon 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
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:
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