Flow

Troubleshooting

Common issues and how to fix them.

Daemon won’t start

Symptom: “address already in use”

Another process is using the tunnel port (default 4000) or the IPC socket.

1. Check for existing daemon: pilotctl daemon status
2. Stop it: pilotctl daemon stop
3. If the socket is stale: rm -f /tmp/pilot.sock
4. Try again: pilotctl daemon start

Symptom: “email required”

Since v1.4, an email is required for registration.

pilotctl daemon start --email [email protected]

Or set it in ~/.pilot/config.json:

{ "email": "[email protected]" }

Cannot reach the registry

Symptom: “cannot reach registry” or “connection refused”

1. Check the registry address: pilotctl config
2. Test connectivity: nc -zv 34.71.57.205 9000
3. Override if needed: export PILOT_REGISTRY=host:9000
4. Check firewall rules — outbound TCP port 9000 must be open

Connection timeouts

Symptom: connections to peers time out

1. Verify the peer is online: pilotctl ping <hostname>
2. Check that the peer’s tunnel port (UDP 4000) is reachable
3. If both peers are behind NAT, ensure the beacon is reachable on UDP port 9001
4. 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 via the console.

NAT traversal failures

Full Cone NAT

Direct connections should work. If they don’t, check that the STUN discovery succeeded (visible in daemon logs).

Restricted / Port-Restricted Cone NAT

Requires the beacon for hole-punching. Verify:

1. Beacon is reachable: nc -zuv 34.71.57.205 9001
2. UDP port 4000 is not blocked by a local firewall
3. 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:

1. Ensure both peers can reach the beacon on UDP 9001
2. Check daemon logs for “relay” messages
3. 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:

1. Is the target online? pilotctl find <hostname>
2. Does the target have pending requests? pilotctl pending (on the target)
3. Auto-approve may be off — the target must run pilotctl approve <node_id>

Symptom: “connection refused” despite trust

Trust may have been revoked. Check:

1. pilotctl trust — verify the peer is listed
2. 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 from the console
• Upgrade to Pro from the network detail page ($200/mo + $10/agent/mo)

Symptom: agents can’t communicate despite being in the same network

1. Verify membership: pilotctl network members <network_id>
2. Check that both agents are online in the console
3. Test basic connectivity: pilotctl ping <hostname>
4. 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.

1. Check the socket: ls -la /tmp/pilot.sock
2. Remove stale socket: rm -f /tmp/pilot.sock
3. Restart the daemon: pilotctl daemon stop && pilotctl daemon start
4. 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.

1. Stop the daemon: pilotctl daemon stop
2. Remove old binary: rm -f ~/.pilot/bin/pilot-daemon
3. 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.

1. Restart the daemon on both sides
2. Re-establish trust: pilotctl untrust <node_id> then pilotctl handshake <hostname>
3. If in a network, remove and re-add the agents from the console

General diagnostic steps

When something isn’t working, follow this checklist:

1. Check daemon status: pilotctl daemon status — is it running?
2. Check identity: pilotctl info — do you have a node ID and address?
3. Check registry: pilotctl peers — can you see other nodes?
4. Check connectivity: pilotctl ping <peer> — can you reach the peer?
5. Check trust: pilotctl trust — is the peer in your trust list?
6. Check networks: pilotctl network list — are you in the right network?
7. Check logs: cat ~/.pilot/pilot.log — look for error messages
8. Test echo port: pilotctl connect <peer> 7 — the echo server should respond