Error catalog

This page lists the errors Axiom shows users, grouped by where you see them: in the editor when a flow run fails, and in HTTP responses when you call the API. Each entry gives the exact error shape, the cause, and the fix.

How errors name nodes and edges#

Flow run errors identify nodes by their canvas id — the per-placement id you see on the node card in the editor (for example id-bad or node-1716492048192) — never by the marketplace node name. This matters when a flow contains two placements of the same node: the error names the specific placement that failed, so you can find it on the canvas directly.

Edges are named by quoting both endpoints. An edge error reads:

edge "id-bad" → "echo-merge": EvaluateEdge adapter: transform TRANSFORM_PREFIX failed: prefix needs a string to prepend, e.g. prefix("hi ")

Here id-bad and echo-merge are the canvas ids of the edge's source and destination nodes.

When a failure is attributed to a specific edge or node, the result panel at the bottom of the editor also shows the failure kind (for example EDGE_ADAPTER) and a Show on canvas button. Clicking it selects the offending edge — or node, when the failure has no edge attribution — on the canvas so you can open and fix it. See Debug a flow for the full debugging workflow.

Flow run errors in the editor#

When an execution fails, the flow status pill above the canvas shows Failed, the result panel header shows Execution Failed, and the panel's Output tab contains the error text. The errors you can see:

When your own node code raises an exception, the handler's error message is surfaced verbatim: it appears on the NODE_FAILED event in the result panel's Execution tab, attributed to the failing placement's canvas id.

Secret authorization errors (grant_required)#

A node receives one of your secrets only after you have explicitly granted that secret to that exact node version, in the console, after reviewing its source. When that consent is missing the run is refused with HTTP 403 and a machine-readable body:

{
  "error": "grant_required",
  "message": "this flow cannot run: 1 secret requirement(s) are not authorized — …",
  "missing": [
    {
      "node_ulid": "01J…",
      "slot": "ANTHROPIC_API_KEY",
      "reason": "not_granted",
      "remedy": "grant it in the console, after reviewing the node's source",
      "console_url": "https://…/console/grants/new?node=01J…&slot=ANTHROPIC_API_KEY"
    }
  ]
}

An AI agent that hits this cannot resolve it itself — that is deliberate. Granting is a human review step, so the agent's job is to relay the missing[] list (each entry has a console_url) to a person, who reviews the code and grants. The same reason values also appear as node-visible status markers, so ax.secrets.status(name) inside a node reports the same cause.

Edge adapter (CEL) errors#

An edge adapter's right-hand side is a bare CEL expression (or a plain field pick) evaluated against the source message. A failing expression produces a CEL error inside an edge error (see above). The failure modes:

CEL string helpers such as toUpper, toLower, trim, size, and join are available in the adapter scope; call them directly (toUpper(text)), not through a pipe. A destination field path (the mapping key) that contains ( or ) is rejected at compile time as a malformed field name.

Whole message-typed field picks copy the message byte-for-byte, so they are only valid between the same message type. These are rejected at compile time (never at run) — the fix is to reconstruct the destination in CEL, field by field:

Constructing a message in CEL#

The reshape those compile-time errors point you to — a CEL object or array literal, or a .map() building elements — is the supported way to fill a message-typed or repeated-message destination field:

adapter:
  # a repeated message field, built element by element
  working_hours: '[{"start": window_start, "end": window_end}]'
  # the same thing from a list already in scope
  busy: 'attendees.map(a, {"intervals": a.busy})'
  # the whole destination message at once (the reserved `self` target)
  self: '{"working_hours": [{"start": start, "end": end}], "duration_seconds": 1800}'

The constructed value is serialized to JSON and decoded into the destination message, so its keys must be the destination's proto field names and its leaf values must match those fields' kinds. Keys that match no field are ignored; an object matching no field at all is rejected (see the from_json rows below).

In-band node errors — they are DATA, and yours to handle (ADR-228)#

A node that returns successfully with an error-shaped output field populated is a SUCCESSFUL node. The engine does not inspect your output payload and does not infer a failure from a field's name. A field called error, error_message or *_error is ordinary data: it flows down edges, an adapter can read it, a condition can test it, a compose can pick it.

A node reports a real failure through one channel only — NodeResponse.error (ADR-115) — which the worker classifies, retries (ADR-114) and routes down on_error edges.

Nothing forces you to read an in-band error field. ADR-187's compile gate was removed by ADR-225, and ADR-226's runtime promotion was reverted by ADR-228. An in-band failure you do not read is silently dropped, and nothing warns you (F-020/F-027, accepted deliberately).

Gate the dependent write — the strong form. A conditional edge means a poisoned value never reaches the database:

- from: hash
  to: insert_user
  condition: { op: CEL, cel: 'error == ""' }
  adapter: { password_hash: phc_hash }

(The consumer's join then needs the skip-tolerant shape.)

Or surface it in the output compose — the minimum form, fine for a terminal node whose result nothing else consumes:

error: { cel: 'inputs.hash.error != "" ? "signup failed: " + inputs.hash.error : ""' }

on_error: edges are for real node failures (a crash, a timeout, an explicit NodeResponse.error) — not for in-band error fields, which never reach them.

Authoring mock errors#

Errors from the mocks: section of a flow.yaml — the per-node fixtures described in Mock nodes while authoring a flow. The first group is raised by axiom flow validate and axiom flow compile; the second refuses to publish anything mocked.

Compile and validate#

Publish#

Publish never strips mocks silently — going live is always an explicit recompile.

HTTP API errors when invoking a flow#

Errors from POST /invocations/v1/flows/invoke and its streaming variant. For the full request/response contract see the HTTP API reference.

Authentication, rate limiting, and quotas#

Structured invoke errors#

Invoke failures with a known cause return a structured body:

{
  "error": "payload_too_large",
  "message": "payload exceeds hard cap: actual=17825792 max=16777216",
  "max_bytes": 16777216,
  "actual_bytes": 17825792
}

Failures that don't classify return 500 with {"accepted": false, "error_message": "<detail>"}.

Timeouts#

With "wait": true, if the execution does not complete within the timeout (default 30 seconds), the response is still 202 — the execution keeps running:

{
  "accepted": true,
  "execution_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "error_message": "timeout waiting for flow result (30s)"
}

Set "timeout_seconds" to wait longer, or look the execution_id up later in execution history. On the streaming endpoint, a timeout ends the stream with a final frame whose error is "timeout waiting for pipeline result"; a flow that fails mid-stream ends with a final frame whose error carries the flow run error described above.

A request that is accepted and delivered but whose execution runs to a failure (for example, the input did not match the flow's start-node schema) returns HTTP 202 with "result":{"success":false,...} and surfaces the worker's diagnostic in both result.error_message and the top-level error_message — so a synchronous caller can tell a delivered failure apart from a timeout or transport error without polling execution history.

HTTP API errors when invoking a single node#

Errors from the per-node JSON endpoint POST /invocations/v1/nodes/{owner}/{pkg}/{version}/{node} (also accepts a node id in place of the name path):

The binary-protobuf variant POST /invocations/v1/nodes/invoke validates its base64 payload against the node's current input schema before forwarding: bytes whose wire shape doesn't match (an undeclared field number, or a wire type conflicting with the declared kind), or any payload whose node schema can't be resolved, return HTTP 400 with {"success":false,"error_message":"payload does not match the node's current input schema: <detail>"}.

HTTP API errors when pre-warming a flow#

Errors from POST /invocations/v1/flows/warm (see Pre-warm a flow). Authentication, rate-limit, and quota failures return the same bodies as invoking a flow above — a warm debits the same daily invocation quota an invoke does. Pre-warm adds these ownership and availability cases:

Execution history and debug API errors#

Errors from the execution-history and debugging endpoints (used by Debug a flow):

• Execution history and event requests return 404 with {"error":"execution not found"} when the execution id doesn't exist for your tenant.
• GET /invocations/v1/executions/{id}/checkpoints/{checkpoint_id} returns 404 with {"error":"checkpoint_not_found_or_expired","detail":"checkpoint may have been evicted by TTL policy (default 30d)"} — checkpoints expire after a retention window (default 30 days), so debug a recent execution instead.
• Agent memory operations return standard statuses: 404 when a memory entry or session is not found, 400 for invalid arguments, 403 for permission denied, 401 for unauthenticated requests, and 429 when resource limits are exhausted.

All endpoints are tenant-scoped: a valid id belonging to another tenant behaves exactly like a nonexistent one (404), never 403 — see Sandboxing and tenancy.