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.

Edge transform errors#

Transforms run inside edge adapters; at runtime a failing transform produces transform TRANSFORM_<NAME> failed: <message> inside an edge error (see above). The messages per transform function, as written in adapter expressions:

upper, lower, trim, and length take no required arguments and do not fail at runtime.

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.

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):

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.