Troubleshooting

Every flow execution — from the test pane, the API, a share link, Slack, or a schedule — lands in the flow's run history with its status, cost, per-node trace, and error context. So the first move when a flow misbehaves is never to guess: open the dev tools (toggle Devtools in the flow's subnav), find the run, and read what actually happened. This page is the map from symptom to cause.

Reading a run's status

Two framing notes. First, partial is a completion status. The flow produced what it could and told you why the rest is missing. Second, a timed-out run shows a timeout status in run history, while a synchronous API caller sees 504 timeout — same run, two vantage points.

The run says partial

The values keys in a form-shape input must match each input node's key setting (or its type default — "data", "prompt"). Keys that don't line up mean those input nodes get nothing, and the run reports partial with a message like "Completed with missing input values." The same status appears when output nodes aren't connected to anything that produces a value.

The fix is mechanical: open the dev drawer's Quickstart tab — it renders the exact request body for this flow, with the real keys. Copy it. Don't reconstruct the envelope from memory.

My flow times out

A run's time budget is timeoutMs — default 60 seconds, maximum 600,000 ms (10 minutes), settable per request on the run endpoint. Two distinct situations look identical from outside:

The flow legitimately needs longer. Chains of model calls add up — five sequential 15-second generations is 75 seconds, already past the default. Pass a higher timeoutMs from your integration. For interactive surfaces, stream the run instead of raising the ceiling — users see tokens immediately even when the total is long.

Something is stalled. Open the run in the dev tools and read the Trace waterfall: every node shows its duration and start offset, so the node that dominates the bar — or never completes — is your culprit. Common finds: one model call doing the work of three, a node waiting on a slow external call, or parallel branches that silently serialized because one feeds the other.

Retrying a timed-out run unchanged mostly reproduces it. Change one of the inputs to the equation first: the ceiling, the flow, or the model.

It works in the test pane but not via the API

The test pane and the API run the same flow through the same machinery. When they disagree, one of three configuration gaps is almost always the reason:

1. Publish state. Production calls should pin { "source": { "kind": "published", "version": "…" } } — and that 404s with flow_not_published if the flow has never been published, or the pinned version doesn't exist. The test pane runs the draft, which always exists. Publish a version, then pin it. (Ship to production)
2. The input envelope. The test pane builds the envelope for you; your integration builds it by hand. Wrong kind, or values keys that don't match the input nodes, produce validation errors or partial runs. Again: the Quickstart tab has the exact body.
3. The credential's workspace. An API key sees only the workspace that minted it. A key from another workspace gets 404 not_found for a flow you can see fine in the editor. Mint the key in the workspace that owns the flow.

Every API run also lands in the dev drawer's Runs tab, so you can compare a failing API run against a working test-pane run side by side — same trace format, same I/O packets.

The output shape changed on my integration

Flow outputs are keyed by each output node's key setting — a flow with an output node keyed reply returns { "reply": … }. Two edits silently change that contract: renaming an output key, and adding or removing output nodes.

If your integration runs the draft (the default when source is omitted), it inherits every saved edit immediately — including shape changes someone made mid-afternoon. The discipline that prevents this:

• Pin production to a published version. A pinned integration cannot drift; changing what it runs requires deliberately publishing and re-pinning. The dev drawer's Versions tab shows what's published and when.
• Treat output-key renames as breaking changes. Publish them as a new version and update callers on your schedule, exactly as you'd version an API of your own.

If the shape already changed under you: the run history shows the outputs of every past run, so you can pinpoint the exact run — and therefore the exact edit window — where the shape flipped.

A scheduled run failed

Schedules run the flow's published version on a cadence with a fixed saved input. When a scheduled run fails or times out, the failure is delivered through the schedule's own delivery channel — a failed email digest emails you the failure, a notification schedule rings the bell with it. No silent gaps.

To diagnose one:

• The schedule row shows its last run status — ok, partial, error, or timeout — at a glance.
• Every scheduled run is in the flow's run history, labeled as scheduled and filterable to its schedule. Open it and read the trace like any other run.
• The usual causes are the usual suspects: the published version regressed (re-publish or re-pin), the saved input no longer matches the flow's input nodes after an edit (partial — update the schedule's input), the workspace ran out of inference credit, or the run outgrew its time budget.

Remember that schedules follow publish: editing the draft doesn't change what the clock runs until you publish.

Where to look — the dev tools

One panel, five tabs, most answers:

• Runs — every execution, newest first, from all sources (test pane, API, share links, Slack, schedules). Select a run for Trace (a per-node waterfall synced to the canvas — hover a row, the node highlights) and I/O (each node's inputs and outputs as a two-column JSON split, plus the error message and server response on failures).
• Versions — what's published, when, under what label. The pin targets for production.
• Evals — Caliper scores for this flow, when you've wired evaluation.
• Usage — spend and run volume over time, split by status. Where a slow cost leak or a rising error rate becomes visible.
• Quickstart — the flow's public Flow ID and a copy-paste request body with the correct input keys.