> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armature.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Armature MCP API structured error codes reference

> Structured JSON-RPC error codes returned by Armature MCP tools—with causes, affected operations, and remediation steps for each code.

When an Armature MCP tool call fails, the endpoint returns a JSON-RPC error whose `data` field contains an `ApiError` object. The `code` field in that object identifies the specific failure. Some errors include a `details` object with `fieldErrors` and `warnings` arrays that pinpoint exactly which field or policy entry caused the problem.

```json theme={null}
{
  "code": "validation_failed",
  "details": {
    "fieldErrors": [
      { "field": "changes.criteria[0].position", "message": "Position does not exist." }
    ],
    "warnings": []
  }
}
```

Use the `code` value to branch your error-handling logic. The `fieldErrors` array, when present, tells you exactly which field to fix before retrying.

<Note>
  A `401 unauthenticated` response—not a JSON-RPC error—means your API key is revoked, malformed, or missing from the `Authorization` header. Verify the key at [Settings → API keys](/settings/api-keys) and check that you are sending it as `Authorization: Bearer amt_<key-id>_<secret>`. See [Authentication](/mcp-api/authentication) for details.
</Note>

## Error code reference

<AccordionGroup>
  <Accordion title="proposal_not_found">
    **Code:** `proposal_not_found`

    **Affected tools:** `apply_workflow_change`, `armature://workflow-change-proposals/{id}` resource

    The proposal ID you referenced does not exist or has already been deleted. This can happen if you supply an incorrect ID, if the proposal was never created, or if it was removed by the daily cleanup process (unapplied proposals older than seven days are deleted from the database).

    **Remediation:** Verify the proposal ID from the `propose_workflow_patch` or `draft_regression_workflow_from_run` response. If the proposal is gone, re-run the staging tool to create a new one.
  </Accordion>

  <Accordion title="proposal_expired">
    **Code:** `proposal_expired`

    **Affected tools:** `apply_workflow_change`

    The proposal exists but is older than 24 hours and can no longer be applied. Armature marks proposals as expired after 24 hours to prevent stale changes from being applied to a workflow that may have changed significantly since the proposal was staged.

    **Remediation:** Stage a fresh proposal against the current workflow version using `propose_workflow_patch` or `draft_regression_workflow_from_run`, present the new diff for approval, and then apply.
  </Accordion>

  <Accordion title="base_version_stale">
    **Code:** `base_version_stale`

    **Affected tools:** `apply_workflow_change`

    The workflow has been updated since this proposal was staged. Armature uses optimistic concurrency against `baseVersionId`—if the workflow version has advanced, applying the proposal could overwrite changes made after the proposal was created.

    The error response includes the current version ID.

    **Remediation:** Re-run `propose_workflow_patch` against the current workflow version, review the new diff, obtain fresh approval, and retry `apply_workflow_change` with the new proposal ID.
  </Accordion>

  <Accordion title="validation_failed">
    **Code:** `validation_failed`

    **Affected tools:** `propose_workflow_patch`, `apply_workflow_change`

    The proposed workflow spec failed schema or policy validation. The `details.fieldErrors` array contains one entry per invalid field, with the field path and a human-readable message explaining the problem.

    Common causes include invalid criterion positions, unrecognized field names, missing required fields, or values that fall outside allowed ranges.

    **Remediation:** Read `armature://schemas/workflow` to confirm the expected shape for each field. Fix each entry in `fieldErrors` and re-stage the proposal. If criteria positions are invalid, inspect the current workflow spec to verify which positions exist.
  </Accordion>

  <Accordion title="unknown_tool_policy_entry">
    **Code:** `unknown_tool_policy_entry`

    **Affected tools:** `propose_workflow_patch`

    A tool name listed in `toolPolicy.allowed_tools` or `toolPolicy.blocked_tools` does not appear in the MCP server's active tool catalog. Armature validates the catalog when staging a proposal—if validation finds a reference to an unknown tool, it returns this error.

    **Remediation:** Read `armature://mcp-servers/{id}/tool-catalog` to see the current list of active tools. If the catalog is out of date, ask an admin or owner to run `sync_mcp_server_capabilities` to refresh it, then retry the proposal. If you need to reference a tool not yet in the catalog, set `allowUndiscoveredTools` in the proposal to receive a warning instead of a hard error.
  </Accordion>

  <Accordion title="forbidden_role">
    **Code:** `forbidden_role`

    **Affected tools:** `apply_workflow_change`, `run_workflow_now`, `sync_mcp_server_capabilities`

    Your API key's role does not have permission to perform this operation. The role permission matrix is:

    | Operation                      | viewer | editor | admin | owner |
    | ------------------------------ | :----: | :----: | :---: | :---: |
    | `apply_workflow_change`        |    —   |   yes  |  yes  |  yes  |
    | `run_workflow_now`             |    —   |   yes  |  yes  |  yes  |
    | `sync_mcp_server_capabilities` |    —   |    —   |  yes  |  yes  |

    **Remediation:** Use an API key with a role that has the required permission. API key roles are frozen at creation time. If you need a higher-permission key, generate a new one from [Settings → API keys](/settings/api-keys) with the appropriate role. See [Roles](/mcp-api/roles) for the full permission matrix.
  </Accordion>

  <Accordion title="workflow_inactive">
    **Code:** `workflow_inactive`

    **Affected tools:** `apply_workflow_change`, `run_workflow_now`

    The target workflow is currently paused and cannot be run or modified through the MCP API. Armature prevents changes to paused workflows to avoid creating drift between the paused state and any applied patches.

    **Remediation:** Reactivate the workflow from the Armature dashboard before retrying the operation.
  </Accordion>

  <Accordion title="auth_profile_unavailable">
    **Code:** `auth_profile_unavailable`

    **Affected tools:** `run_workflow_now`, `propose_workflow_patch`

    The MCP auth profile required by the workflow—used to authenticate tool calls to the target MCP server—is missing, revoked, or inaccessible to the agent running the workflow.

    **Remediation:** Verify that the auth profile referenced by the workflow is active and correctly configured in the Armature dashboard. Never pass credentials directly as tool arguments—use dashboard-managed auth profiles and `secret_ref` placeholders in workflow specs.
  </Accordion>

  <Accordion title="dispatch_failed">
    **Code:** `dispatch_failed`

    **Affected tools:** `run_workflow_now`

    The run could not be dispatched due to a worker infrastructure error. The run was not started.

    **Remediation:** Retry `run_workflow_now`. If the error persists, check your Armature organization's status or contact support. You can also verify recent run dispatch activity using `get_org_health`.
  </Accordion>

  <Accordion title="run_wait_timeout">
    **Code:** `run_wait_timeout`

    **Affected tools:** `run_workflow_now` (when `wait: true`)

    The run was dispatched successfully but did not reach a terminal state within the wait timeout period. The run is still in progress—Armature does not cancel it when the timeout elapses.

    **Remediation:** The returned error response includes the run ID. Use `inspect_run` with that ID to poll for the run's current status. Once the run completes, you can proceed with `compare_runs` or read `armature://runs/{id}/trace` for the full trace.
  </Accordion>

  <Accordion title="cooldown_pending">
    **Code:** `cooldown_pending`

    **Affected tools:** `sync_mcp_server_capabilities`

    A capability sync was requested but the five-minute cooldown period for this MCP server has not yet elapsed since the last sync. The cooldown is based on the timestamp of the most recent tool snapshot for the server.

    **Remediation:** Wait until the cooldown elapses and retry. If you are an admin or owner and need to force an immediate sync, pass `force: true` in the `sync_mcp_server_capabilities` call to bypass the cooldown.

    <Note>
      The `force` bypass is available only for explicit admin and owner calls. Implicit syncs that occur during proposal validation always respect the cooldown and cannot be forced.
    </Note>
  </Accordion>

  <Accordion title="target_unreachable">
    **Code:** `target_unreachable`

    **Affected tools:** `sync_mcp_server_capabilities`, `run_workflow_now`

    Armature could not contact the target MCP server. The server may be offline, the endpoint URL may be incorrect, or a network or firewall rule may be blocking the connection.

    **Remediation:** Verify that the target MCP server is running and reachable from Armature's infrastructure. Check the server's endpoint URL and any authentication settings in the Armature dashboard. If the sync fails during proposal validation, Armature continues validation against the stale catalog and returns a `catalog_stale_sync_failed` warning in the proposal response.
  </Accordion>

  <Accordion title="target_returned_invalid_schema">
    **Code:** `target_returned_invalid_schema`

    **Affected tools:** `sync_mcp_server_capabilities`

    The target MCP server responded to `tools/list` but its response did not conform to the MCP schema. The server is reachable but is returning a malformed tool catalog.

    **Remediation:** Inspect the target MCP server's `tools/list` response directly to identify the schema violation. Common causes include missing required fields on tool definitions (such as `name` or `inputSchema`), or non-standard response shapes. Fix the server's `tools/list` implementation and retry the sync.
  </Accordion>
</AccordionGroup>

## Related pages

* [Authentication](/mcp-api/authentication) — API keys, the `Authorization` header, and `401` responses
* [Roles](/mcp-api/roles) — role permission matrix for all tools and operations
* [Triage tools](/mcp-api/tools/triage) — read-only tools that do not return structured errors
* [Repair tools](/mcp-api/tools/repair) — proposal and apply tools that return most structured errors
* [Resources](/mcp-api/resources) — resource URIs and the errors they can return
* [Prompts](/mcp-api/prompts) — guided sequences and their error-handling checkpoints