Error Codes

Reference for errors returned by agentd, the libagent client, and tool invocations.

IPC-level errors

These are returned as Response::Error { message } over the Unix socket when the daemon cannot process a request.

Error message pattern	Cause
`agent not found: <id>`	The specified agent ID does not exist or has already terminated
`permission denied`	The requesting agent lacks the required capability
`invalid request`	The request payload is malformed or missing required fields
`secret not found: <name>`	A `{{secret:<name>}}` handle references an unregistered secret
`no matching policy`	A secret resolution attempt has no active pre-approval policy
`policy expired`	The matching pre-approval policy has passed its `expires_at` timestamp
`policy exhausted`	The matching pre-approval policy has used all its `max_uses` allowances
`mcp server not found: <name>`	`ash mcp attach` referenced an unregistered MCP server name
`agent store: not found: <name>`	`ash agent run` referenced an uninstalled agent name
`hierarchy depth exceeded`	Agent tried to spawn a child beyond the maximum hierarchy depth
`capability escalation denied`	`SpawnChildAgent` `cap_override` contains capabilities not held by the caller
`invalid manifest: <detail>`	Manifest YAML failed validation
`unsupported api version: <v>`	Manifest `apiVersion` is not `scarab/v1`
`lifecycle timeout_secs=0 is invalid`	Manifest declares a zero timeout

Every tool invocation returns a ToolResult with a status field.

Status	Description
`success`	Tool executed and returned a result
`denied`	The agent's capability set does not include `tool.invoke:<tool>`
`not_found`	The requested tool name is not registered in the agent's `ToolRegistry`
`error`	Tool executed but encountered a runtime error (see `output` for details)

Tool	Error	Cause
`fs.read`	`file not found`	The specified path does not exist
`fs.read`	`permission denied`	Path is outside the agent's `fs.read:<scope>` capability
`fs.write`	`path not writable`	Path is outside the agent's `fs.write:<scope>` capability
`fs.delete`	`path not deletable`	Path is outside the agent's `fs.delete:<scope>` capability
`web.fetch`	`network policy violation`	Target host not allowed by the agent's `network.policy`
`web.fetch`	`connection refused`	Remote host rejected the connection
`web.search`	`scrape error`	DuckDuckGo Lite returned an unexpected HTML structure
`lm.complete`	`model not available`	`SCARAB_MODEL` references an unavailable model
`sandbox.exec`	`exec failed`	The sandboxed command could not be spawned
`sandbox.exec`	`timeout`	Sandboxed execution exceeded the time limit
`sensitive-op`	`human denied`	Operator denied the HITL approval request
`sensitive-op`	`approval timeout`	No operator response within `approval_timeout_secs`

Errors returned by the libagent AgentdClient before a response is received from the daemon.

Variant	Description
`ConnectionFailed(io::Error)`	Could not connect to the agentd Unix socket. Check that agentd is running and `SCARAB_SOCKET` is correct.
`EncodeError(serde_json::Error)`	Failed to serialize the request to JSON, or failed to deserialize the response. Indicates a version mismatch or corrupt frame.
`UnexpectedEof`	The socket stream closed before the full response frame was received. agentd may have crashed or restarted.

Returned by ash validate and by AgentManifest::from_yaml().

Error	Cause
`unsupported API version: <v>`	`apiVersion` is not `scarab/v1`
`expected kind 'AgentManifest', got '<k>'`	`kind` field is wrong
`agent name cannot be empty`	`metadata.name` is blank
`invalid capability in manifest: <cap>`	A capability string cannot be parsed
`capability 'net.fetch:*' requires trust_level >= trusted`	Over-privileged capability for the declared trust level
`lifecycle timeout_secs=0 is invalid`	Timeout must be > 0
`scheduler cost_budget must be > 0`	Cost budget must be a positive number

These are not errors in the IPC sense but are recorded as anomaly events:

Event	Trigger
`HighToolInvocationRate`	Tool calls per minute exceeded threshold
`RepeatedToolFailure`	Same tool failed N consecutive times
`CapabilityEscalationAttempt`	Agent used a denied capability
`ResourceExhaustion`	Memory or CPU limit approached
`CostBudgetExceeded`	Scheduler cost budget exhausted

See ash anomaly list to view events.