# Troubleshooting Diagnose Al-Amr failures from structured evidence: the symbolic `code`, numeric `exitCode`, HTTP status, and request ID. Do not repair immutable IDs, digests, release versions, lockfiles, or Registry state by hand merely to make an error disappear. Every entry below names a real stable code, whether retrying as-is is safe, and the next action. ## First response From the Environment, App, or Plugin project, collect these results: ```sh alamr doctor --json --non-interactive alamr inspect --json --non-interactive alamr validate --json --non-interactive alamr status --json --non-interactive ``` `doctor` checks Node.js, the detected package manager, local manifest and lockfile, and Registry health. `inspect` shows the local declaration. `validate` returns field-level problems. `status` requires a valid link and management credential and returns Registry publication state. Record `schemaVersion`, the command, symbolic `code`, numeric `exitCode`, `ok`, `diagnostics`, `nextActions`, `artifacts`, `data`, Registry origin, Project ID, target ID, version, and request ID when present. Remove access tokens, authorization headers, cookies, and secrets before sharing evidence. ## CLI exit codes | Code | Class | Symbolic result code | What to do first | | ---: | ------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------ | | `0` | Success | `ALAMR_OK` | Read structured `data`; do not infer a later publication state | | `1` | Validation or operation failure | `ALAMR_ERROR` | Read field errors, check results, or server error code and correct the input or failed operation | | `2` | Invalid usage | `ALAMR_USAGE` | Run `alamr --help` and correct arguments or supported options | | `3` | Authentication or authorization | `ALAMR_AUTH_REQUIRED` | Verify Registry origin, credential expiry, ownership, and token scope | | `4` | Network | `ALAMR_NETWORK_ERROR` | Check the clean Registry origin, DNS, TLS, proxy, and service health | | `5` | State conflict | `ALAMR_CONFLICT` | Read current Registry status before retrying; protect immutability and optimistic state | HTTP `401` and `403` map to CLI exit code `3`; HTTP `409` maps to exit code `5`. A Registry `429` response should be retried only after a brief wait. Other non-success responses normally map to exit code `1`. ## Authentication and account codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | ------------------------------- | ----------- | --------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- | | `authentication_required` | 401 / 3 | No valid session or token accompanied the request | No | Run `alamr login` for the intended Registry or supply a scoped, expiring project token | | `management_token_invalid` | 401 / 3 | The management credential is expired or wrong for this Registry | No | Log in again or issue a fresh token for that exact Registry and Project | | `csrf_failed` | 403 / 3 | Console/BFF mutation lacked a valid CSRF token | No | Refresh the Console session and repeat the action through the UI or API contract | | `rate_limited` | 429 / 1 | Registry rate limit | Yes, after a brief wait | Preserve the request ID, wait, and retry once; remove uncontrolled retry loops | | `project_access_denied` | 403 / 3 | The user does not own or manage this Project | No | Use an owned Project or an account with the required Project role | | `project_token_scope_denied` | 403 / 3 | The project token lacks the operation scope | No | Issue the minimum required scoped token; publication writes require `publish:write` | | `ALAMR_LOGIN_APPROVAL_REQUIRED` | - / 0 | Device login handoff created; a human must approve it | Not applicable | Pause; the human opens the verification URI and confirms the user code | | `ALAMR_LOGIN_APPROVAL_PENDING` | - / 1 | The human has not approved the device handoff yet | Yes, at the returned interval | Wait `retryAfterSeconds` and run the exact resume command again | | `ALAMR_AUTHORIZATION_DENIED` | - / 1 | The human denied the authorization | No | Restart `alamr login --device --json` only with the human's agreement | CLI login, browser SSO, Environment Runtime tokens, Console sessions, and CI project tokens are separate credential classes. Do not substitute one for another. ## Network and reachability codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | ------------------------------------ | ----------- | ------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------- | | `ALAMR_NETWORK_ERROR` | - / 4 | DNS, TLS, proxy, firewall, timeout, or Registry outage | Yes, after connectivity is restored | Run `doctor --json`; restore connectivity or select the intended healthy Registry | | `artifact_store_unavailable` | 503 / 1 | Public artifact store is unavailable | Yes, after recovery | Wait and retry; do not replace artifacts with synthetic files | | `managed_artifact_store_unavailable` | 503 / 1 | Managed artifact storage is unavailable | Yes, after recovery | Wait and retry the same operation | | `external_npm_registry_unavailable` | 502 / 1 | The upstream npm registry did not respond | Yes, after recovery | Retry the npm-ingestion workflow later | | `presence_unavailable` | 503 / 1 | Presence store is unavailable | Yes, after recovery | Wait for Presence recovery; evidence must come from the Registry store, not the candidate | A catalog read failure and `runtime_coordination_unavailable` are different problems: preserve the route, HTTP status, and problem code. Never fall back from Registry publication state to npm metadata, scene constants, a cached Console view, or a package name. ## Project link and manifest codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | --------------------------------- | ----------- | -------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------- | | `project_not_found` | 404 / 1 | The linked `projectId` does not exist on this Registry | No | Compare `.al-amr/project.json` with the Console/API Project record and relink an owned Project | | `not_environment_project` | 409 / 5 | The linked Project has a different type than the local manifest | No | Link an owned Project of the same type | | `not_app_project` | 409 / 5 | The linked Project is not an App Project | No | Link an owned App Project | | `not_plugin_project` | 409 / 5 | The linked Project is not a Plugin Project | No | Link an owned Plugin Project | | `slug_already_exists` | 409 / 5 | The requested slug is already taken under this Publisher | No | Choose a free slug; do not overwrite the existing record | | `invalid_environment_manifest` | 422 / 1 | A contract field, URL, installation, or composition rule failed | No | Read every `data.errors` entry and fix the named source field; revalidate | | `invalid_plugin_manifest` | 422 / 1 | The Plugin manifest violates the contract | No | Fix the named fields; bump SemVer if a release already exists | | `invalid_app_manifest` | 422 / 1 | The App manifest violates the contract | No | Fix the named fields and prepare a fresh build generation | | `invalid_environment_composition` | 422 / 1 | Declared composition bindings are invalid; `details.issues[]` lists causes | No | Fix the reported port, adapter, or protocol-artifact binding | | `plugin_release_not_found` | 404 / 1 | An installed Plugin release does not exist or is not visible | No | Select an existing published target; do not infer identity from the npm package name | ## Test and publication codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | ------------------------------------------- | ----------- | ---------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------- | | `publication_target_frozen` | 409 / 5 | An identical or conflicting submission already freezes this target | No | Read `alamr status --json`; continue the existing submission instead of creating a duplicate | | `submission_checks_not_allowed` | 409 / 5 | Checks were requested outside `draft` or `checks_failed` | No | Read the current state and use the allowed action for it | | `submission_not_ready` | 409 / 5 | Submit was requested before `ready_for_review`, or it already moved on | No | Confirm state with `status`; treat `in_review` as success for the submit step | | `publication_state_changed` | 409 / 5 | Another actor or request moved the submission | No | Re-evaluate from the current Registry state; do not replay a stale `from` transition | | `artifact_snapshot_changed` | 409 / 5 | The artifact set no longer matches the frozen submission digest | No | Stop; investigate Registry integrity and create a new immutable target when content legitimately changed | | `snapshot_digest_mismatch` | 409 / 5 | Review evidence no longer matches the frozen snapshot digest | No | Stop; never rewrite a digest | | `artifact_digest_mismatch` | 409 / 5 | Review evidence no longer matches the frozen artifact digest | No | Stop; never rewrite a digest | | `dedicated_publication_action_required` | 403 / 3 | The generic transition route was used for checks, submit, or review | No | Call the dedicated `/checks`, `/submit`, or `/review` endpoint | | `backend_protocol_reference_missing` | 409 / 1 | A new backend component does not reference immutable protocol evidence | No | Add the matching OpenAPI/AsyncAPI declaration and packaged file, then test a new release | | `backend_protocol_artifact_bytes_missing` | 409 / 1 | Referenced protocol bytes are absent from the package | No | Package the exact protocol path and regenerate the digest from those bytes | | `backend_protocol_artifact_digest_mismatch` | 409 / 1 | Packaged protocol bytes differ from the declared SHA-256 | No | Regenerate the digest from the packaged bytes; metadata-only evidence cannot be published | | `plugin_release_not_published` | 409 / 1 | An installed Plugin release is not published | No | Install a published release or publish the dependency first | | `plugin_artifact_not_valid` | 409 / 1 | The installed release lacks a valid package artifact | No | The Plugin publisher must create a new valid release/artifact | | `plugin_contract_incompatible` | 409 / 1 | The installed release does not accept the current platform Contracts range | No | Rebuild with the promoted compatible declarations; do not weaken the Registry gate | | `plugin_sdk_incompatible` | 409 / 1 | The hosted or installed SDK SemVer is not accepted | No | Rebuild with the promoted compatible SDK | | `backend_unreachable` | 409 / 1 | The backend health URL is not reachable | Yes, after the endpoint is fixed | Restore health reachability and rerun `alamr test` | | `backend_health_url_required` | 422 / 1 | The deployment declaration is missing its health URL | No | Declare a non-secret health endpoint on the backend origin | | `runtime_verification_deferred` | - / 0 | Authoritative Runtime/Presence verification is deferred until after approval | Not applicable | Continue the lifecycle; this is an informational check outcome, not a failure | For state-by-state recovery procedures see [Publication lifecycle](/docs/publish/publication-lifecycle) and [Recovery and rollback](/docs/publish/recovery). ## Review and publication-admin codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | ----------------------------------------------- | ----------- | --------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------- | | `reviewer_required` | 403 / 3 | The caller is not an authorized reviewer or administrator for this endpoint | No | Use a reviewer/admin account; project tokens are rejected | | `reviewer_separation_of_duty` | 403 / 3 | The submitter attempted to review their own submission | No | Wait for an independent reviewer | | `publisher_separation_of_duty` | 403 / 3 | The approving reviewer attempted to publish the same submission | No | Hand off to a different platform administrator for publication | | `review_work_item_not_found` | 404 / 1 | The review work item does not exist | No | Confirm the submission ID | | `review_work_item_snapshot_mismatch` | 409 / 5 | The work item's snapshot digest changed concurrently | No | Re-read the work item and decide against the current digests | | `review_work_item_artifact_mismatch` | 409 / 5 | The work item's artifact digest changed concurrently | No | Re-read the work item and decide against the current digests | | `review_plugin_artifact_inspection_unavailable` | 409 / 1 | The reviewer artifact stream cannot be served for inspection | Yes, after recovery | Retry the same-origin inspection path; do not accept unverified bytes | | `publication_approval_evidence_unavailable` | 409 / 5 | Approval evidence required for publication is missing or stale | No | Return to review; publication cannot proceed without current approval evidence | | `invalid_review` | 422 / 1 | The review request body violates the contract (for example, reject without notes) | No | Supply the required decision, notes, and expected digests | | `environment_runtime_preview_expired` | 409 / 5 | Legacy web-entry preview expired; current bundles never require this gate | No | Migrate the draft to a bundle entry and run the current one-pass bundle test | | `environment_runtime_preview_not_renewable` | 409 / 5 | Legacy web-entry preview is not renewable | No | Migrate the draft to a bundle entry; do not add a preview step to the current workflow | | `environment_runtime_preview_state_changed` | 409 / 5 | Legacy web-entry preview changed concurrently | No | Re-read only when recovering a historical record; current bundle work is unaffected | | `environment_runtime_proof_required` | 409 / 5 | Legacy web-entry publication lacks its old live Runtime proof | No | Create and test a current immutable bundle revision | | `invalid_environment_preview_renewal` | 422 / 1 | A legacy preview-renewal request violates its retained contract | No | Do not renew for a bundle; create and test a current revision | | `managed_artifact_cache_unavailable` | 503 / 1 | The published-artifact cache cannot serve verified bytes | Yes, after recovery | Wait and retry; the cache fails closed rather than serving unverified bytes | | `project_recovery_admin_required` | 403 / 3 | Rollback requires an administrator | No | Use a platform administrator account | | `invalid_rollback` | 422 / 1 | The rollback request violates the contract | No | Correct the target type, target ID, reason, and plan digest | | `rollback_target_not_eligible` | 409 / 5 | The rollback target is not a still-published, unblocked target of this Project | No | Choose an eligible published target or publish a new one | | `admin_required` | 403 / 3 | The operation requires a platform administrator | No | Use an administrator account; project tokens are rejected | | `invalid_app_availability` | 422 / 1 | The availability request body violates the contract | No | Supply `appId`, `revisionId`, `enabled`, and a 3–1000 character reason | ## Runtime and Presence codes Runtime authorization failures use `application/problem+json` with stable codes. Preserve the HTTP status and `code`. | Code | HTTP | Meaning | Retryable as-is | Next action | | ----------------------------------- | ---- | -------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------- | | `runtime_token_invalid` | 401 | Runtime bearer token or session binding is missing or invalid | No | Restart authorization through the SDK; never substitute a CLI, CI, or Console credential | | `runtime_authorization_expired` | 401 | Authorization, grant, or Runtime session expired or was revoked | No | Use the SDK retry/re-authorization path; a failure signs the person out, never downgrades | | `account_required` | 403 | The Runtime session carries no account, and every world needs one | No | Sign in. There is no entry that does not; the policy this once read was deleted | | `runtime_origin_required` | 403 | The Runtime request carries no browser origin | No | Launch the bundle through the desktop client; do not spoof Origin | | `runtime_origin_mismatch` | 403 | The request origin differs from the session's platform origin | No | Relaunch the exact bundle through the desktop client | | `runtime_origin_unregistered` | 403 | A legacy web origin is not registered for its historical revision | No | Publish a current bundle revision instead of registering a new publisher origin | | `environment_not_available` | 403 | The Environment is not currently available for Runtime authorization | No | Check publication state; a yanked or suspended revision cannot authorize | | `runtime_session_standby` | 409 | The authorized page does not own the active lease | No | Explicitly activate this page before calling protected Runtime APIs | | `runtime_session_superseded` | 409 | A newer page or device became active | No | Continue in the newer Runtime or explicitly choose **Activate this page** | | `runtime_lease_stale` | 409 | The lease ID/version expired or no longer matches the active fence | No | Activate again through the SDK and restart fenced work | | `runtime_coordination_unavailable` | 503 | Registry cannot safely coordinate the single active Runtime | Yes, after recovery | Wait and retry through the SDK; the failure is intentionally closed | | `environment_preview_access_denied` | 403 | The caller is not a Project member or administrator for this preview | No | Enter with an authorized account | | `invalid_presence_heartbeat` | 422 | The heartbeat violates the contract | No | Send heartbeats only through the SDK | The SDK stores browser tokens in memory. Reloading or losing transaction state may require authorization again; that is safer than persisting bearer tokens in local storage. ## Plugin Grant and backend deployment codes | Code | HTTP | Meaning | Retryable as-is | Next action | | -------------------------------------- | ---- | ----------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- | | `plugin_not_installed` | 403 | The Plugin is not installed in this Environment revision | No | Install the exact release with `alamr add` | | `plugin_release_version_mismatch` | 409 | The Grant request names a different release than the installation | No | Request a Grant for the exact installed release | | `plugin_release_unavailable` | 409 | The installed release is not currently published | No | Install a published release | | `plugin_release_emergency_blocked` | 403 | The release is under an active emergency block | No; wait for the block to resolve | Wait for a platform reviewer to resolve the emergency block | | `backend_component_not_declared` | 409 | The component is not declared by the installed release | No | Declare the component in a new Plugin release | | `backend_deployment_not_found` | 409 | No deployment exists for the component | No | Create and publish the backend deployment revision | | `backend_deployment_pending` | 503 | The deployment revision is not published yet | Yes, after publication | Publish the deployment revision, then retry | | `backend_deployment_unhealthy` | 503 | The deployment health check is failing | Yes, after the endpoint recovers | Restore backend health; evidence is refreshed on retry | | `backend_deployment_suspended` | 403 | The deployment was administratively suspended | No | Publish a replacement deployment revision after reviewer approval | | `backend_deployment_emergency_blocked` | 403 | The deployment is under an active emergency block | No; wait for the block to resolve | Wait for a platform reviewer to resolve the emergency block | | `grant_scope_denied` | 403 | The requested Grant scope is not declared by the installation | No | Request only reviewed, declared scopes | | `scope_denied` | 403 | Scope admission was denied, timed out, or malformed | No | Check the Environment backend scope-admission endpoint; denial fails closed generically | ## App build and launch codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | ----------------------------------- | ----------- | ------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------- | | `app_build_artifact_required` | 409 / 5 | The App revision has no immutable bundle binding | No | Run `alamr build`, then the one-pass `alamr test --yes --json` | | `app_build_snapshot_changed` | 409 / 5 | The submission names a different bundle digest than the bound one | No | Do not bind different bytes to a submitted revision; build and test a new revision | | `app_build_artifact_invalid` | 409 / 5 | The bound inventory no longer recomputes to the digest it was bound under | No | Create a new App revision; a bound inventory is never edited in place | | `app_contract_incompatible` | 409 / 1 | The manifest Contracts range does not accept the current platform | No | Rebuild with the promoted compatible Contracts declarations | | `app_build_artifact_immutable` | 409 / 5 | An attempt was made to rebind an existing build artifact | No | Create a new App revision for changed bytes | | `app_build_artifact_binding_closed` | 409 / 5 | The revision's one build binding is already closed | No | Create a new App revision for changed bytes | | `app_not_available` | 404 or 403 | The App revision is not enabled for Runtime | No | A platform administrator must enable the exact published revision | | `app_account_required` | 403 | The App requires an account principal | No | Enter with an account session | | `parent_runtime_not_active` | 409 | The parent Environment Runtime is not active | No | Activate the parent Runtime before launching the App | | `parent_runtime_lease_stale` | 409 | The parent Runtime lease no longer matches the active fence | No | Re-establish the parent Runtime and relaunch | | `app_origin_required` | 403 | The launch did not come from the platform-assigned App origin | No | Relaunch the held bundle through AppHost; do not self-host the App frontend | | `app_launch_code_invalid` | 401 | The one-time launch code is missing, consumed, or expired | No | Restart the launch through the host Widget | ## Hub placement codes | Code | HTTP / exit | Meaning | Retryable as-is | Next action | | --------------------------------------- | ----------- | -------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------ | | `invalid_hub_placement` | 422 / 1 | The placement request violates the contract | No | Correct identifiers and the 3–1000 character reason | | `hub_placement_zone_not_found` | 404 / 1 | The Hub or Zone does not exist | No | Confirm the Hub and Zone identifiers with `alamr admin hubs list --json` | | `hub_placement_target_already_assigned` | 409 / 5 | The destination is already assigned to another slot in the Hub | No | Choose another eligible Environment or clear the conflicting assignment | Placement conflicts also cover fixed slots, Hub as its own destination, and ineligible or missing targets. Do not work around them by editing IDs or Hub source; see [Hub placement operations](/docs/publish/hub-placement). ## Portal and Release Set codes | Code | HTTP | Meaning | Retryable as-is | Next action | | ---------------------------------------- | ---- | ------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- | | `ALAMR_PLATFORM_RELEASE_UNAVAILABLE` | 503 | No schema-valid promoted Release Set exists; public commands are disabled | Yes, after promotion | Wait for a promoted Release Set; never substitute guessed versions or dist-tags | | `ALAMR_RELEASE_VERIFICATION_UNAVAILABLE` | 503 | No catalog-verified Release Set is available at the verification route | Yes, after verification | Wait for release verification to complete | ## Evidence for escalation Provide: - UTC time and Registry origin; - exact command and CLI version; - process code and redacted JSON result; - request ID and stable Registry error code; - Project, Environment, Plugin, release/revision, submission, deployment, and artifact IDs that are relevant; - manifest and artifact digests or integrity values; - current state from `alamr status --json`; - minimal reproduction and whether the failure is local, browser, Registry, or backend-component specific. Never provide bearer tokens, authorization codes, PKCE verifiers, cookies, private keys, project token secrets, or secret deployment configuration. For terminology use the [Product and security glossary](/docs/product/glossary). For review evidence see [Human review](/docs/publish/human-review), and for recovery procedures by state see [Recovery and rollback](/docs/publish/recovery).