Error Codes Reference

All errors thrown by Tervos packages are instances of TervosError from @tervos/core. Every error carries a typed code, a human-readable message, and — where possible — a fix string suggesting how to resolve it.

TervosError Shape

class TervosError extends Error {
  code: TervosErrorCode;                 // Typed code (see table below)
  message: string;                       // What went wrong
  fix: string | null;                    // Suggested resolution
  details: Record<string, unknown>;      // Structured context
}

import { TervosError, TervosErrorCode } from "@tervos/core";

try {
  await runtime.executeTask(taskId);
} catch (err) {
  if (err instanceof TervosError && err.code === TervosErrorCode.ACTION_DENIED) {
    console.error(err.message, "→", err.fix);
  }
}

Error Codes

Code	Meaning	Typical fix
TERVOS_ERR_INVALID_TRANSITION	An agent or task was asked to move to a lifecycle state that isn’t reachable from its current state (e.g., activating a TERMINATED agent).	Check the current state with tervos status; follow the lifecycle state machine (PENDING → ACTIVE → SUSPENDED → TERMINATED for agents).
TERVOS_ERR_AGENT_NOT_FOUND	The referenced agent ID or DID doesn’t exist in this organization.	Check agent IDs in TERVOS.yaml; run tervos status to list registered agents.
TERVOS_ERR_ACTION_DENIED	The policy engine denied the action (forbid matched, or no permit matched — default-deny).	Inspect the policy.evaluated event in tervos audit for the matched policies and reason; grant the agent the needed capability in TERVOS.yaml.
TERVOS_ERR_BUDGET_EXCEEDED	The action’s estimated cost exceeds the agent’s remaining budget (SAFE-004).	Raise the agent’s budget in TERVOS.yaml, or review budget.charged events to see where the budget went.
TERVOS_ERR_APPROVAL_REQUIRED	The action needs human approval before it can proceed (agent autonomy is supervised).	Run tervos approve <id> or tervos deny <id> --reason "..."; pending requests appear in tervos status.
TERVOS_ERR_APPROVAL_TIMEOUT	An approval request expired before a human responded.	Re-run the task to generate a fresh approval request; consider --dev mode for local development (auto-approves, still policy-checked).
TERVOS_ERR_MANIFEST_INVALID	TERVOS.yaml failed schema validation (bad field, broken cross-reference, cyclic reporting graph, or budget roll-up violation).	Run tervos validate — each issue includes the field path and a suggested fix.
TERVOS_ERR_MANIFEST_NOT_FOUND	No TERVOS.yaml found at the expected path.	Run tervos init to scaffold one, or pass the path explicitly: tervos validate ./path/to/TERVOS.yaml.
TERVOS_ERR_TASK_NOT_FOUND	The referenced task ID doesn’t exist.	List tasks with tervos status; check the taskId spelling.
TERVOS_ERR_TASK_DEPENDENCY_UNMET	The task depends on another task that hasn’t completed.	Complete or cancel the blocking task first; tervos status shows dependency state.
TERVOS_ERR_TASK_ALREADY_ASSIGNED	The task is already assigned to another agent.	Unassign or cancel the existing assignment before reassigning.
TERVOS_ERR_UNAUTHORIZED	The principal’s identity could not be verified (bad signature, expired token, unknown DID).	Check that the agent’s key exists in .tervos/keys/; re-run tervos start to re-issue tokens.
TERVOS_ERR_INTERNAL	An unexpected internal error.	This is a bug — please open an issue with the error details and the output of tervos audit --limit 20.

Design Notes

• Default-deny: when no policy matches an action, the result is ACTION_DENIED, not an internal error. Check the audit log rather than the stack trace.
• Every error is an event too: policy denials and budget stops appear in the event log (policy.evaluated with decision: "deny"), so the audit trail explains errors after the fact.