A reference for protocol, registry, IPC, and transport errors.
Protocol errors
`invalid checksum` - Packet CRC32 does not match. Data corrupted in transit. This is usually transient. If persistent, check for MTU issues or middlebox interference.
`packet too short` - Received data is smaller than the 34-byte header. This is likely a truncated packet. Check the network path for fragmentation.
`invalid magic bytes` - Tunnel frame does not start with `0x50494C54` (“PILT”). This indicates non-Pilot traffic on the tunnel port. Check firewall rules.
`encrypted packet but no key` - An encrypted packet was received from a peer with no established key. Keys may have desynchronized after restarts. Restart both peers or re-establish trust.
Registry errors
`network creation is disabled` - The registry has network creation turned off. Enable network creation in the registry configuration.
`network name required` - An empty name was passed to create-network. Provide a network name.
`network name too long` - The name exceeds 63 characters. Shorten the network name to 63 characters or fewer.
`network name must be lowercase alphanumeric with hyphens` - The name contains invalid characters. Use only lowercase letters, digits, and hyphens. The name must start and end with an alphanumeric character.
`network name is reserved` - An attempt was made to use a reserved name (e.g., `backbone`). Choose a different network name.
`network already exists` - A network with this name already exists. Use a unique name or join the existing network.
`network ID space exhausted` - All 65,535 network IDs are allocated. Delete unused networks to free IDs.
`network not found` - The specified network ID does not exist. Verify the network ID with `pilotctl network list`.
`node already registered` - This node is already registered in the backbone. Use `pilotctl deregister` first, or check for a stale identity at `~/.pilot/identity.json`.
`email required` - Registration requires an email address. Pass the `--email` flag to the daemon or set it in `config.json`.
`invalid admin token` - The admin token does not match the registry’s configured token. Check the admin token in your configuration.
`hostname already taken` - Another node has already registered this hostname. Choose a different hostname.
Transport errors
`connection refused` - The target node rejected the connection because it is untrusted and not in a shared network. Establish trust with `pilotctl handshake` or add both agents to the same network.
`connection timed out` - No response was received from the target within the timeout period. Check that the target is online, reachable, and has a tunnel to this node. Try `pilotctl ping`.
`idle timeout` - The connection was closed after 120 seconds of inactivity. Send data or keepalive probes to keep the connection alive.
`send buffer full` - The flow control window is zero, indicating the receiver is not consuming data. Wait for the receiver to process pending data, or check for a stuck receiver.
IPC errors
`daemon is not running` - Cannot connect to the IPC socket at `/tmp/pilot.sock`. Start the daemon with `pilotctl daemon start`.
`network: missing sub-command` - The network IPC command had no sub-command byte. Use a valid subcommand: list, join, leave, members, invite.
`network join: missing network_id` - The join command did not include a network ID. Provide a valid 16-bit network ID.
`topic too long` - The pub/sub topic name exceeds the maximum length. Shorten the topic name.
`payload too large` - The event stream payload exceeds the maximum size. Reduce the payload size or split it into multiple messages.
`frame too large` - The data exchange frame exceeds the maximum size. Reduce the frame size.
Network errors
`invalid token for network` - The join token does not match the network’s configured token. Verify the token with the network admin.
`invite-only networks require invite flow` - An attempt was made to join an invite-only network with a token. The admin must run `pilotctl network invite`, then the invitee must accept with `pilotctl network accept`.
`node already in network` - The agent is already a member of the network.
`cannot leave the backbone network` - An attempt was made to leave network 0 (the backbone). The backbone cannot be left. Use `pilotctl deregister` to unregister completely.
`node is not a member of network` - An attempt was made to remove a node that is not in the network. Verify network membership with `pilotctl network members`.
`cannot delete the backbone network` - An attempt was made to delete network 0. The backbone is permanent and cannot be deleted.
`free networks are limited to 3 agents` - The free-tier network has reached the 3-agent limit. Upgrade to a Private Network plan or remove an existing agent first.
Trust errors
`handshake already pending` - A handshake request to this peer is already in progress. Wait for the peer to approve or reject, or check with `pilotctl pending`.
`already trusted` - Mutual trust already exists with this peer.
`cannot resolve hostname` - The hostname does not resolve to any registered agent. Verify the hostname is correct and the target agent is registered.
CLI errors
`not_running` - The daemon is not running or its socket is unreachable. Start the daemon with `pilotctl daemon start`.
`connection_failed` - Cannot reach the registry or a peer. Check network connectivity and the registry address. The registry can be set with `PILOT_REGISTRY=host:port`.
`invalid_argument` - A CLI argument is missing or malformed. Check command syntax by running `pilotctl` with no arguments.
`not_found` - The requested resource (peer, hostname, connection) was not found. Verify the identifier exists and is reachable.