A reference for protocol, registry, transport, IPC, network, trust, and CLI errors, including descriptions and resolution steps.
Protocol errors
`checksum mismatch`: Packet CRC32 does not match. Data corrupted in transit. Usually transient. If persistent, check for MTU issues or middlebox interference.
`packet too short`: Received data is smaller than the 34-byte header. Likely a truncated packet. Check network path for fragmentation.
`(silently dropped)`: A tunnel frame with an unrecognized magic prefix is silently discarded. This indicates non-Pilot traffic on the tunnel port. Check firewall rules.
`encrypted packet but no key`: Received an encrypted packet from a peer with no established key. Keys may have desynchronized. Restart both peers or re-establish trust.
Registry errors
`network creation is disabled`: Registry has network creation turned off. Enable network creation in registry configuration.
`network name required`: Empty name passed to create-network. Provide a network name.
`network name too long`: Name exceeds 63 characters. Shorten the network name to 63 characters or fewer.
`network name must be lowercase alphanumeric with hyphens`: Name contains invalid characters. Use only lowercase letters, digits, and hyphens. Must start and end with alphanumeric.
`network name is reserved`: Attempted to use a reserved name such as `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`.
`registration requires public_key`: Registration was attempted without a public key, or the registry is full. Ensure the daemon has an identity at `~/.pilot/identity.json`.
`invalid email`: The `--email` flag or `email` config key is malformed. Use a valid `local@domain` address, or omit it to have one synthesized.
`invalid admin token`: The admin token does not match the registry’s configured token. Check the admin token in your configuration.
`hostname already in use`: Another node has already registered this hostname. Choose a different hostname.
Transport errors
`connection refused`: 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.
`dial timeout`: No response from the target within the timeout period. Check that the target is online and reachable. Try `pilotctl ping`.
`idle timeout`: Connection closed after 120 seconds of inactivity. Send data or keepalive probes to keep the connection alive.
`send buffer full`: Flow control window is zero because the receiver is not consuming data. Wait for the receiver to process pending data.
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, or invite.
`network join: missing network_id`: Join command did not include a network ID. Provide a valid 16-bit network ID.
`topic too long`: Pub/sub topic name exceeds the maximum length. Shorten the topic name.
`payload too large`: Event stream payload exceeds the maximum size. Reduce the payload size or split into multiple messages.
`frame too large`: 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`: Tried to join an invite-only network with a token. Use the invite flow via `pilotctl network invite` and `pilotctl network accept`.
`node already in network`: The agent is already a member of the network.
`cannot leave the backbone network`: Attempted to leave network 0 (the backbone). The backbone cannot be left. Use `pilotctl deregister` to unregister completely.
`node is not a member of network`: Tried to remove a node that is not in the network. Verify membership with `pilotctl network members`.
`cannot delete the backbone network`: Attempted to delete network 0. The backbone is permanent and cannot be deleted.
`network membership limit reached`: The network reached its configured member cap. Raise the network policy's member limit or remove an existing member.
Trust errors
`handshake already pending`: A handshake request to this peer is already in progress. Wait for the peer to respond or check status 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`: Daemon is not running or socket is unreachable. Start the daemon with `pilotctl daemon start`.
`connection_failed`: Cannot reach the registry or a peer. Check network connectivity and registry address. The registry can be set with `PILOT_REGISTRY=host:port`.
`invalid_argument`: A CLI argument is missing or malformed. Check command syntax with `pilotctl`.
`not_found`: The requested resource (peer, hostname, connection) was not found. Verify the identifier exists and is reachable.