Troubleshooting

Every flow execution — from the test panel, 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 message. So the first move when a flow misbehaves is never to guess: open Devtools on the flow, 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 Devtools → Quickstart — it gives you 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 gets 10 minutes. You can give it less by passing a smaller timeoutMs on the run endpoint, but not more. Two distinct situations look identical from outside:

The flow legitimately needs longer. Chains of model calls add up, and a long agent loop can run past ten minutes of real work. Split it into flows you call in sequence, or cut the work each run does. For interactive surfaces, stream the run — people 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 panel but not via the API

The test panel and the API run the same flow. 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 panel runs the draft, which always exists. Publish a version, then pin it. (Ship to production)
2. The input envelope. The test panel 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 Devtools → Runs, so you can compare a failing API run against a working one from the test panel side by side.

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. Devtools → Versions 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 panel, 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.