[ Switch to styled version → ]
Reference for protocol, registry, transport, IPC, network, trust, and CLI errors, with resolution steps.
invalid checksum: Packet CRC32 does not match. Data corrupted in transit. Resolution: Usually transient. If persistent, check for MTU issues or middlebox interference.packet too short: Received data is smaller than the 34-byte header. Resolution: Likely a truncated packet. Check network path for fragmentation.invalid magic bytes: Tunnel frame does not start with 0x50494C54 ("PILT"). Resolution: 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. Resolution: Keys may have desynchronized after restarts. Restart both peers or re-establish trust.network creation is disabled: Registry has network creation turned off. Resolution: Enable network creation in registry configuration.network name required: Empty name passed to create-network. Resolution: Provide a network name.network name too long: Name exceeds 63 characters. Resolution: Shorten the network name to 63 characters or fewer.network name must be lowercase alphanumeric with hyphens: Name contains invalid characters. Resolution: Use only lowercase letters, digits, and hyphens. Must start and end with alphanumeric.network name is reserved: Attempted to use a reserved name (e.g., backbone). Resolution: Choose a different network name.network already exists: A network with this name already exists. Resolution: Use a unique name or join the existing network.network ID space exhausted: All 65,535 network IDs are allocated. Resolution: Delete unused networks to free IDs.network not found: The specified network ID does not exist. Resolution: Verify the network ID with pilotctl network list.node already registered: This node is already registered in the backbone. Resolution: Use pilotctl deregister first, or check for stale identity at ~/.pilot/identity.json.invalid email: The --email flag (or email config key) is malformed. Resolution: Use a valid local@domain address, or omit the flag and let the daemon synthesise <fingerprint>@nodes.pilotprotocol.network.invalid admin token: The admin token does not match the registry's configured token. Resolution: Check the admin token in your configuration.hostname already taken: Another node has already registered this hostname. Resolution: Choose a different hostname.connection refused: Target node rejected the connection (untrusted and not in a shared network). Resolution: Establish trust with pilotctl handshake or add both agents to the same network.connection timed out: No response from the target within the timeout period. Resolution: Check that the target is online, reachable, and has a tunnel to this node. Try pilotctl ping.idle timeout: Connection closed after 120 seconds of inactivity. Resolution: Send data or keepalive probes to keep the connection alive.send buffer full: Flow control window is zero; the receiver is not consuming data. Resolution: Wait for the receiver to process pending data, or check for a stuck receiver.daemon is not running: Cannot connect to the IPC socket at /tmp/pilot.sock. Resolution: Start the daemon: pilotctl daemon startnetwork: missing sub-command: The network IPC command had no sub-command byte. Resolution: Use a valid subcommand: list, join, leave, members, invite.network join: missing network_id: Join command did not include a network ID. Resolution: Provide a valid 16-bit network ID.topic too long: Pub/sub topic name exceeds the maximum length. Resolution: Shorten the topic name.payload too large: Event stream payload exceeds the maximum size. Resolution: Reduce the payload size or split into multiple messages.frame too large: Data exchange frame exceeds the maximum size. Resolution: Reduce the frame size.invalid token for network: The join token does not match the network's configured token. Resolution: Verify the token with the network admin.invite-only networks require invite flow: Tried to join an invite-only network with a token. Resolution: Ask the admin to run pilotctl network invite, then accept with pilotctl network accept.node already in network: The agent is already a member. Resolution: No action needed - the agent is already joined.cannot leave the backbone network: Attempted to leave network 0 (the backbone). Resolution: The backbone cannot be left. Use pilotctl deregister to fully unregister.node is not a member of network: Tried to remove a node that is not in the network. Resolution: Verify network membership with pilotctl network members.cannot delete the backbone network: Attempted to delete network 0. Resolution: The backbone is permanent and cannot be deleted.free networks are limited to 3 agents: Free-tier network has reached the 3-agent limit. Resolution: Upgrade to a Private Network plan or remove an existing agent first.handshake already pending: A handshake request to this peer is already in progress. Resolution: Wait for the peer to approve or reject, or check with pilotctl pending.already trusted: Mutual trust already exists with this peer. Resolution: No action needed.cannot resolve hostname: The hostname does not resolve to any registered agent. Resolution: Verify the hostname is correct and the target agent is registered.not_running: Daemon is not running or socket is unreachable. Resolution: Start the daemon: pilotctl daemon startconnection_failed: Cannot reach the registry or a peer. Resolution: Check network connectivity and registry address. Try PILOT_REGISTRY=host:port.invalid_argument: A CLI argument is missing or malformed. Resolution: Check command syntax with pilotctl (no args) for usage.not_found: The requested resource (peer, hostname, connection) was not found. Resolution: Verify the identifier exists and is reachable.