Running & Debugging

Run a workflow on demand, follow execution live, and diagnose problems from per-node output and logs.

Running a workflow

For workflows using Versions & previews, select Production or a named preview above the editor. The selector shows its deployed version and whether it is On, Off, Blocked, or Stopping. Opening a workflow with configured destinations selects production by default; a link to a preview keeps that preview selected. Selecting a destination never starts an execution.

• Dry-run candidate simulates the selected destination's saved candidate. Its execution record includes the destination even when it shares a version with another preview.
• Run deployed version uses that destination's approved live activation and selected connections. It is unavailable while the destination is off. It can change real data and consume credits.
• Manage versions lets you name a saved workflow version or create a named preview from it. A name changes presentation; the immutable version number, content and approvals stay the same.

The legacy editor, for workflows that have not set up previews, retains these actions:

From the Editor:

• Dry-run candidate — the primary test action. It pins the newest saved candidate version, completes inline even when Redis is enabled (queued: false), simulates effects, and records requestedTarget: "candidate", the versionId, resourceMode: "simulated", and reviewIdentity.
• Run candidate live — requires an explicit confirmation bound to the expected candidate version. It uses real workspace credentials and external systems (resourceMode: "workspace-live"). This is not a separate or runtime-isolated environment.
• Run from a block — start at startNodeId. When a prior run is still current, upstream outputs can be reused; if stale, dependencies re-run.

Programmatic: POST /api/v1/workflows/{id}/execute with a workspace-scoped API key (403 otherwise). Public execution targets the active version by default. Body: input?, startNodeId?, dryRun?, target?, executionTargetId?, expectedVersionId?, confirm?. Idempotency-Key supported. Returns { run, execution, queued, statusUrl, cancelUrl } — 202 when queued to BullMQ, 201 when inline. Default input is { prompt: "API execution" }. Invalid JSON body → 400.

Pass executionTargetId to select a preview or production destination explicitly. Live runs pin its approved activation; target: "candidate", dryRun: true simulates that destination's prepared version. The typed workflows.execute tool accepts the same destination. Retrying an idempotency key with a different destination, activation or API principal is rejected; an inaccessible destination never falls back to production.

Candidate execution defaults to dry run. A live candidate request must send target: "candidate", dryRun: false, confirm: true, and the current expectedVersionId; stale versions fail closed. Active v1 continues serving production while candidate v2 is tested, reviewed, and synchronized. Only an explicit deploy changes the active version.

tRPC workflows.run (session) targets the candidate by default and also accepts executionTargetId, executeNodeId, executeDependencies, sourceRunId, target, expectedVersionId, confirm, and trigger (manual | webhook | schedule | copilot | api | email | rss). A source execution must belong to the same workflow and destination. A named destination uses its approved activation for live execution; live candidate requests cannot bypass its publication checks.

Publish, promote and stop a preview

1. Open Manage versions, select a saved version and choose Create preview. Give it a name. The preview starts off.
2. Choose its connections explicitly and save them. Sharing a production account can change production data, even though the preview has a separate webhook URL. Choose an exact child deployment for each called workflow; stopping a child blocks dependent executions.
3. Prepare its AIMS request. Open approvals keeps the workflow and destination selected. A preview approval does not authorize production. Current roles, independent review and recent MFA still apply.
4. The eligible reviewer chooses Approve and enable, which publishes if connections, AIMS and repository requirements pass. Check On and the expected deployed version; do not deploy again. If approval was saved but publication was blocked, resolve the displayed requirement and use Retry enabling. Deploy version also lets an authorized operator publish an already approved version from the editor. With no linked repository, Git is not required; a linked preview needs the exact reviewed commit and production requires its merge. Publication turns on enabled trigger nodes; explicitly disabled nodes stay disabled. Updating a preview preserves its existing webhook URL.
5. From a deployed preview, choose Promote to production. Decide whether to switch off the source after publication; this is selected by default. Review production's own connections and AIMS request. The production reviewer uses Approve and enable for this separate request. Production keeps serving its current version while review is pending. Successful promotion changes production and applies the selected source-stop choice together. Keeping the source on leaves both destinations enabled, with separate webhook URLs.

Use the destination switch to stop it, or open Workflows → Active deployments to find and switch off destinations across workflows. On means it can accept events, even with zero executions. Blocked means its deployment cannot currently pass an authority or connection check. Stopping means new events are blocked while queued, running or waiting executions are being canceled. Effects already sent to an external provider may finish. Switching on requires a successful publication check; a failed request does not display a successful activation.

Production's Previous deployments list offers Restore deployment for snapshots whose AIMS grant explicitly permitted future production reactivation. The original grant must still be valid and its connections and dependencies available. Restoration creates a new activation from that exact snapshot, preserves production's URL, and cancels the replaced generation. It does not restore or undo external data. An old deployment without this permission offers Prepare rollback approval. It copies the historical version and connection references into a separate rollback request while the current deployment and editor candidate stay unchanged. Complete the new AIMS review, then publish. Request new approval provides the same recovery path when a previous reactivation grant expired or was revoked. Current connection and Git checks still apply.

Moving a workflow to the trash stops all its destinations and requests cancellation of pending executions. Restoring it from the trash leaves those destinations off. Changing destinations, leaving for Approvals, reloading, or using browser Back/Forward warns before discarding unsaved editor changes.

The former environment promotion screen is retained as history, rather than a second publication flow.

Poll GET /api/v1/workflows/{id}/status?runId= until a terminal status. pollAfterMs is 1000 while active, null when finished. Without runId, the handler returns the workflow plus up to 20 recent runs.

Run status

waiting is not finished. Timer/event/approval detail lives on the runtime checkpoint, not on the v1 status string. GET /api/v1/runs can filter status=waiting. Cancel is allowed on queued / running (409 otherwise); a parked waiting run is not canceled by that endpoint.

Queue vs direct and leases: Workers and recovery.

Executing one step

Session POST /api/workflows/{id}/execute-step (Member+). Body: { nodeId, sourceRunId?, executionTargetId?, expectedVersion?, allowRealEffects? }. Set executionTargetId to the selected preview or production destination; live execution requires expectedVersion for its approved deployed version. Trigger nodes cannot run this way. Seeds come from the chosen source run, else the latest run with outputs for direct dependencies. Pinned output wins over run output.

In the inspector, Execute step tests the saved candidate with simulated effects. Run deployed step uses the selected destination's approved deployed version, even when the editor has a newer candidate; its confirmation names the destination and version. It requires Admin or Owner execution access and recent MFA, and is unavailable while the destination is off or if the node is absent from the deployment. If MFA expires, verify in the dialog and confirm the destination and version again; verification does not run the step automatically. Viewers can inspect the workflow but cannot edit, simulate, publish or run it. Live effects require allowRealEffects: true. Successful executions write an audit event (node, source run, effect classification/mode, pin ids, live flag).

There is no v1 execute-step route.

Pinning data

Session GET|PUT|DELETE /api/workflows/{id}/pin-data (Member+). GET/DELETE: ?nodeId=&executionTargetId=. PUT: { nodeId, items, executionTargetId?, expectedVersion? } (array or object). Omitting the destination selects the legacy Production namespace. 413 if over 256 KB. 422 if items is neither array nor object.

Pins belong to the selected destination. Two previews made from the same workflow version have separate pins; creating a preview does not copy Production's test data. The inspector and workflows.prepare-test-data use the same destination scope. Removing a node clears only that destination's pins, and step execution cannot use another destination's pins or source runs.

Pins are fixtures, not a cache. The inspector shows Pinned or May be outdated when node config drifted. Secret-like values store as redacted. Pins expire after 30 days (FLUXUS_PIN_DATA_RETENTION_DAYS; 0 disables the sweeper). The worker tick deletes expired pins.

Inspecting a run

Live node badges, duration, and output preview. Inspector: input, output, request, response (secrets redacted). Logs terminal streams the active run. Run selector: Run N of M. Multi-item output: item selector plus Table view.

Events: session GET /api/runs/{id}/events (SSE, Last-Event-Id reconnect). Full history: Executions and /api/v1/runs.

Expression preview (canvas): session POST /api/workflows/{id}/evaluate-expression (rate-limited, size-capped). Not on v1.

Node execution flags

Stored on node settings (including n8n import):

These apply to normal runs, re-runs, and single-step executions.

Debugging failures

• Fix and re-run from the failing block (seeded outputs).
• POST /api/v1/runs/{id}/rerun — new run, original input (201).
• Resume waits: timer sweep / resume hook / approval API.
• Workflow Copilot can read the last run.

If the run never left queued, treat it as a worker/Redis problem, not a node bug.

Parked Human Tasks and Agent approvals

A run parked at a Human Task (approval) or a pending Agent tool approval shows waiting. It holds no live worker and its compute segment is closed while asleep, so it neither reserves nor bills compute until it resumes. Find the work in the Tasks inbox or the run detail's task card, which show the safe reason, the relevant policy/version identifiers, and the allowed action. An Agent tool proposal is immutable — approve executes the exact hashed proposal after a fresh guardrail and authority recheck; rejecting with feedback creates a new proposal rather than editing the pending one. For detection, diagnosis, and safe recovery of parked, orphaned, racing, or lost-signal states, see the Human Task recovery runbook.

Next steps

For an AI node in a named destination, set its provider endpoint and model in the candidate graph before review. The selected credential supplies secret bytes. A URL or API-version field stored inside credential JSON cannot override the approved graph when that destination runs. Rotations are checked again at dispatch; if a connection changes during a node, retry with the current connection.