Skip to main content

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.

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. 
{
  "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.
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 and check that you are sending it as Authorization: Bearer amt_<key-id>_<secret>. See Authentication for details.

​
Error code reference

Code: proposal_not_foundAffected tools: apply_workflow_change, armature://workflow-change-proposals/{id} resourceThe 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.
Code: proposal_expiredAffected tools: apply_workflow_changeThe 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.
Code: base_version_staleAffected tools: apply_workflow_changeThe 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.
Code: validation_failedAffected tools: propose_workflow_patch, apply_workflow_changeThe 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.
Code: unknown_tool_policy_entryAffected tools: propose_workflow_patchA 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.
Code: forbidden_roleAffected tools: apply_workflow_change, run_workflow_now, sync_mcp_server_capabilitiesYour API key’s role does not have permission to perform this operation. The role permission matrix is:
Operationviewereditoradminowner
apply_workflow_change—yesyesyes
run_workflow_now—yesyesyes
sync_mcp_server_capabilities——yesyes
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 with the appropriate role. See Roles for the full permission matrix.
Code: workflow_inactiveAffected tools: apply_workflow_change, run_workflow_nowThe 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.
Code: auth_profile_unavailableAffected tools: run_workflow_now, propose_workflow_patchThe 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.
Code: dispatch_failedAffected tools: run_workflow_nowThe 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.
Code: run_wait_timeoutAffected 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.
Code: cooldown_pendingAffected tools: sync_mcp_server_capabilitiesA 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.
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.
Code: target_unreachableAffected tools: sync_mcp_server_capabilities, run_workflow_nowArmature 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.
Code: target_returned_invalid_schemaAffected tools: sync_mcp_server_capabilitiesThe 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.
  • Authentication — API keys, the Authorization header, and 401 responses
  • Roles — role permission matrix for all tools and operations
  • Triage tools — read-only tools that do not return structured errors
  • Repair tools — proposal and apply tools that return most structured errors
  • Resources — resource URIs and the errors they can return
  • Prompts — guided sequences and their error-handling checkpoints