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

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.