Exit codes
A grouped taxonomy. Every aidokit command maps its failures into these codes. Codes are stable across releases.
Groups
| Code | Group | Meaning |
|---|---|---|
| 0 | Success | Command completed. |
| 1 | Generic error | Unhandled or uncategorised error. |
| 2 | Bad invocation | Unknown flag, missing argument, mutually-exclusive flags. |
| 10 | Prereq missing | A required prerequisite is not installed or too old. |
| 11 | Adapter | Adapter not found, failed to load, or version-incompatible. |
| 12 | Stack pack | Stack pack not found or failed to load. |
| 13 | Conformance | Conformance harness or doctor check failed. |
| 20 | Filesystem | File write / read / permission failure. |
| 21 | MCP | MCP install / remove command failed. |
| 30 | Migration | Migration script failure. |
| 40 | User | User cancelled an interactive prompt. |
| 50 | Network | Network operation failed (search, package fetch). |
| 60 | Validation | Schema validation failed. |
| 70 | Conflict | File conflict during sync; user did not resolve. |
Reserved AidoError.code values
| Code | Exit | Notes |
|---|---|---|
BAD_INVOCATION | 2 | Argument parsing failure. |
PREREQ_MISSING | 10 | Required prereq not installed. |
PREREQ_VERSION_TOO_LOW | 10 | Installed but below minimum version. |
ADAPTER_NOT_FOUND | 11 | Adapter package not installed. |
ADAPTER_LOAD_FAILED | 11 | Adapter package failed to import. |
ADAPTER_SPEC_MISMATCH | 11 | Adapter's spec version differs from CLI's. |
STACK_PACK_NOT_FOUND | 12 | Stack pack not installed. |
CONFORMANCE_FAILED | 13 | Harness or doctor check failed. |
FS_WRITE_FAILED | 20 | File write error. |
FS_PERMISSION_DENIED | 20 | Insufficient permissions. |
MCP_INSTALL_FAILED | 21 | MCP registration command exited non-zero. |
MCP_NOT_IN_CATALOG | 21 | Requested MCP id not in catalog (no --custom-url). |
MIGRATION_FAILED | 30 | Migration script error. |
USER_CANCELLED | 40 | User declined an interactive prompt. |
NETWORK_FAILED | 50 | Network operation failed. |
OFFLINE | 50 | Network needed but AIDO_OFFLINE=1. |
VALIDATION_FAILED | 60 | Artifact failed schema validation. |
SYNC_CONFLICT | 70 | Sync diff has conflicts and user did not resolve. |
Error envelope
Human mode:
output
✗ Prerequisite missing: Claude Code (PREREQ_MISSING)
Detected: No `claude` command found on PATH.
Hint: Install Claude Code via:
curl -fsSL claude.ai/install.sh | bash
Or set --skip-prereq-check to bypass.
JSON mode (--json):
json
{
"ok": false,
"command": "init",
"error": {
"code": "PREREQ_MISSING",
"exitCode": 10,
"message": "Prerequisite missing: Claude Code",
"details": { "prereq": "claude-code", "minVersion": "2.1.32" },
"hint": "Install Claude Code via: curl -fsSL claude.ai/install.sh | bash"
}
}
Conventions
- Error codes are
SCREAMING_SNAKE_CASE. - Prefix indicates category:
PREREQ_*,ADAPTER_*,MCP_*,FS_*,MIGRATE_*. - Codes are stable across releases — new codes are added; existing codes never renamed.
exitCodein the JSON envelope matches the process exit code.