Get started

Error codes

acf-mcp uses standard MCP/JSON-RPC error codes. Every error embeds a kind field (machine-readable), a human description and an action hint. This page lists the common errors and how to fix them.

→Tip

Every error includes a hint field inside data. When your agent receives an error, read the hint first — it is calibrated to give the shortest remediation action.

Error shape

Errors follow the JSON-RPC 2.0 spec: a numeric code, a short message, a structured data field. The data.kind field is the stable, machine-readable identifier you should match to branch your recovery logic.

error-example.jsonjson

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32602,
    "message": "InvalidEnumValue: autonomy_level must be one of N0, N1, N2, N3",
    "data": {
      "kind": "InvalidEnumValue",
      "field": "autonomy_level",
      "received": "N4",
      "allowed": ["N0", "N1", "N2", "N3"],
      "hint": "Use N3 for fully autonomous agents acting without human-in-the-loop."
    }
  }
}

Common errors

InvalidEnumValue-32602

Raised by REASON tools when an enum field (autonomy_level, principle_id, role, etc.) is not in the canonical doctrine list. The hint indicates the most likely intended value given the input.

InputTooShort-32602

Raised when a text field (typically description or use_case_domain) is shorter than 20 characters. The engine refuses inputs too thin to produce a defensible qualification.

DoctrineSnapshotMismatch-32602

Raised when the call requests a doctrine_version that is not the one currently loaded by the server. Update the server (npx -y acf-mcp@latest) or drop the parameter to use the current version.

ResourceNotFound-32601

Raised by READ tools when the requested acf://… URI is not in the loaded corpus. Check the canonical spelling via list-fiches or search.

RateLimitExceeded-32000

HTTP mode only. The calling IP has exceeded 60 calls/minute (default). Retry after the retry-after value in data.

Parse and protocol errors

ParseError-32700

The client sent invalid JSON. Check your serializer.

InvalidRequest-32600

The JSON-RPC message is malformed (jsonrpc != 2.0, missing method, etc.).

MethodNotFound-32601

Unknown method. Use tools/list and resources/list to discover supported methods.

InternalError-32603

Unexpected internal server error. Open an issue with logs attached (see contributing).

Recovery strategies

InvalidEnumValue / InputTooShort — ask the user to clarify, or recall the canonical values via the glossary resource.
DoctrineSnapshotMismatch — tell the user the requested doctrine version is no longer loaded; propose the current version.
ResourceNotFound — use search or list-fiches to propose a near-match URI.
RateLimitExceeded — implement an exponential backoff; check your calls are not in a loop.

Error shape

Common errors

Parse and protocol errors

Recovery strategies

See also