# Error catalog

Al-Amr failures carry stable `ALAMR_*` codes. Automate against the code and
the structured fields, never against prose. The machine-readable core index is
served at `/agent/v2/errors/index.json`; [Troubleshooting](/docs/errors/troubleshooting)
covers the wider operational set with symptom-first guidance.

## How to read a failure

Every CLI JSON result uses one envelope: `ok`, symbolic `code`, process
`exitCode`, structured `diagnostics`, `nextActions`, and `artifacts`. Preserve
the first structured error; later errors are usually its consequence. The
process exit codes are stable: `0` success, `1` validation or operation
failure, `2` invalid usage, `3` authentication or authorization failure, `4`
network failure, `5` state conflict.

## Bootstrap and Release Set codes

<!-- sources: platform/developer-portal/lib/platform-release.ts, packages/cli/src -->

| Code                                     | Retryable | Meaning                                                       | Next action                                                     |
| ---------------------------------------- | --------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| `ALAMR_PLATFORM_RELEASE_UNAVAILABLE`     | Yes       | No promoted Release Set is available at the public bootstrap. | Fail closed; track `/status` and retry when a set is promoted.  |
| `ALAMR_RELEASE_VERIFICATION_UNAVAILABLE` | Yes       | No catalog-verified Release Set at the verification route.    | Wait for release verification and use the exact Release Set ID. |

## Authentication and account codes

<!-- sources: packages/cli/src -->

| Code                            | Retryable | Meaning                                                | Next action                                                        |
| ------------------------------- | --------- | ------------------------------------------------------ | ------------------------------------------------------------------ |
| `ALAMR_AUTH_REQUIRED`           | No        | Missing, expired, or insufficient credential (exit 3). | Sign in with `alamr login` or provide a scoped `AL_AMR_TOKEN`.     |
| `ALAMR_AUTHORIZATION_DENIED`    | No        | Authenticated, but the action is not allowed.          | Check the Project role and token scope.                            |
| `ALAMR_LOGIN_APPROVAL_REQUIRED` | No        | Device login handoff created; a human must approve it. | The human opens `verificationUriComplete` and confirms `userCode`. |
| `ALAMR_LOGIN_APPROVAL_PENDING`  | Yes       | The human has not approved the device handoff yet.     | Retry with the returned interval, then resume.                     |

## Network codes

<!-- sources: packages/cli/src -->

| Code                  | Retryable | Meaning                                                          | Next action                                         |
| --------------------- | --------- | ---------------------------------------------------------------- | --------------------------------------------------- |
| `ALAMR_NETWORK_ERROR` | Yes       | DNS, TLS, proxy, firewall, timeout, or Registry outage (exit 4). | Check the configured Registry URL and network path. |

## Usage and conflict codes

<!-- sources: packages/cli/src -->

| Code             | Retryable | Meaning                                            | Next action                                                               |
| ---------------- | --------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
| `ALAMR_ERROR`    | No        | Validation or operation failure (exit 1).          | Read the structured `diagnostics` and fix the reported cause.             |
| `ALAMR_USAGE`    | No        | Invalid arguments or unsupported options (exit 2). | Run `alamr --help` and correct the invocation.                            |
| `ALAMR_CONFLICT` | No        | Registry state conflict (exit 5).                  | Refresh state with `alamr status`; never convert a conflict into a retry. |

## Workflow gate codes

<!-- sources: packages/cli/src/commands/workflow.ts, packages/cli/src/workflow-execution.ts -->

| Code                               | Retryable | Meaning                                            | Next action                                                          |
| ---------------------------------- | --------- | -------------------------------------------------- | -------------------------------------------------------------------- |
| `ALAMR_WORKFLOW_APPROVAL_REQUIRED` | No        | The workflow reached a declared human gate.        | Present the actor, target, snapshot, and evidence digest to a human. |
| `ALAMR_WORKFLOW_APPROVED`          | No        | The gate decision is recorded (informational).     | Continue the workflow.                                               |
| `ALAMR_WORKFLOW_IDEMPOTENT_REPLAY` | No        | A completed workflow was replayed (informational). | Do not repeat the mutation; use the recorded result.                 |

## Journey proof codes

The authoring Journeys fail closed with these completion-assertion codes when a
required proof is missing. Remediation is always: perform the missing step for
the exact revision, release, or artifact — never edit evidence.

<!-- sources: platform/developer-portal/lib/authoring-journey-builder-v2.ts -->

| Code                                                    | Meaning                                                               |
| ------------------------------------------------------- | --------------------------------------------------------------------- |
| `ALAMR_PUBLICATION_NOT_PUBLISHED`                       | The target is not in the published state the journey expects.         |
| `ALAMR_REQUESTED_BEHAVIOR_NOT_PROVEN`                   | The behavior declared for the journey was not demonstrated.           |
| `ALAMR_ENVIRONMENT_CONSUMER_ENTRY_MISSING`              | No independent consumer entry into the published Environment.         |
| `ALAMR_HUB_VISITOR_ENTRY_MISSING`                       | No real visit from the Hub after placement.                           |
| `ALAMR_HUB_PLACEMENT_NOT_CLEARED`                       | A Hub placement was not cleared after the proof.                      |
| `ALAMR_APP_LAUNCH_MISSING`                              | The published App revision was not launched in a Runtime.             |
| `ALAMR_APP_WORKSPACE_MODE_MISSING`                      | The declared Workspace mode was not proven.                           |
| `ALAMR_APP_CONSUMER_PRINCIPAL_NOT_INDEPENDENT`          | The App consumer proof used a non-independent principal.              |
| `ALAMR_PLUGIN_CONSUMER_INSTALL_MISSING`                 | The exact Plugin release was not installed in a consumer Environment. |
| `ALAMR_PLUGIN_CONSUMER_ENVIRONMENT_PUBLICATION_MISSING` | The consumer Environment itself is not published.                     |
| `ALAMR_PLUGIN_CONSUMER_PRINCIPAL_NOT_INDEPENDENT`       | The Plugin consumer proof used a non-independent principal.           |
| `ALAMR_PLUGIN_FRONTEND_ACTIVATION_MISSING`              | The Plugin's frontend behavior was not activated in the consumer.     |
| `ALAMR_PLUGIN_BACKEND_ACTION_MISSING`                   | The Plugin's backend action was not exercised in the consumer.        |

## See also

- [Troubleshooting](/docs/errors/troubleshooting) — symptom-first operational
  index with the wider code set.
- [AI-native development](/docs/ai-native) — the discovery order and Context
  Pack contract agents follow.
- [Recovery and rollback](/docs/publish/recovery) — checkpoints, resume, and
  rejection handling.
- [CLI reference](/docs/reference/cli) — command surface and JSON envelope.