> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Launching and debugging workflow runs

> Launch a workflow with its declared inputs, read run status and outcome, track outcome receipts and notifications, export a debug bundle, and run one draft node in debug.

Every way of starting a workflow (the **Run** action, the Runs tab, the builder's **Run** and **Test run**, and a rerun) reads the selected version's input contract. This page covers launching with those inputs, reading what a run's status and outcome mean, tracking the outcome receipts and notifications a run must deliver, and the debug tools for one run or one draft node.

## What you can do

* Launch a workflow and fill its inputs by their declared role.
* Read a run's **Status** and **Outcome** as separate facts.
* Page through a run attempt's required outcome receipts, and inspect each notification in the run's **Flow** inspector.
* Rebuild a debug slice of a published version with **Debug preview**.
* Export one run's debug bundle from the run inspector.
* Run one node of the current draft in debug against a production run's evidence.

## Launching with workflow inputs

Every launch surface uses the selected workflow version's canonical input contract: the workflow
header **Run** action, the Runs tab, builder **Run** and **Test run**, and reruns from a past run.
The launch dialog presents each input according to its declared role:

* **Parameters** are editable for this run and may be prefilled from a default or the last run.
* **Derived inputs** are computed automatically and shown read-only.
* **Workflow assets** show the currently bound file. Use **Replace** to update that workflow-level
  binding before a new run; reruns preserve the past run's pinned version and input values.

Forge disables launch while the contract or required asset bindings are still loading. A missing
required asset is rejected in the dialog before execution begins. If the canonical contract is
empty, the workflow launches directly without showing an unnecessary dialog.

## Understanding run outcomes

The Runs tab separates **Status** from **Outcome**. Completed records lifecycle; Normal completion,
Exception handled and Error handled describe the selected execution path. Failed remains an
unfinished execution or required handling failure. These are execution facts, not a business-success
rating. Run details show the reason, recorded or reconstructed evidence, affected steps and selected
route facts. See [Execution outcomes](https://docs.gloo.com/forge/console/production/runs.md#execution-outcomes).

![Runs (light)](https://mintcdn.com/gloo-b243725a/IDhN85NU2Ln2Gc4-/forge/images/console/production/runs-light.png?fit=max\&auto=format\&n=IDhN85NU2Ln2Gc4-\&q=85\&s=92dbb6e7bb67108a6710562d7700189c)

Runs — Forge Console at `/production/runs`

New graph runs record outcomes automatically on legacy and native runtimes. Existing exception
routing declarations and actual error recovery are observed without author setup, republishing or
new completion nodes. Ordinary route names never create exceptions. Historical runs without
sufficient evidence show Outcome unavailable. This observation does not opt a workflow into the
staged native delivery contract described below.

## Tracking required outcome receipts

Workflows using the staged outcome-routing contract record required delivery separately from
personal notification preferences. Each run attempt freezes its recipients: the person who starts
an interactive run is included automatically, configured operators cover scheduled and other
automated runs, and expected exceptions or technical failures notify every configured operator.
Muting advisory notifications does not remove these required receipts.

For each attempt, authorized run readers can page through up to 100 receipt obligations at a time.
Each row identifies the terminal, failure, or expected-exception event; its in-app or staged Slack
target; delivery attempts; and one of these states:

* **Pending** — due for delivery or a bounded safe retry.
* **Satisfied** — the personal in-app receipt committed successfully.
* **Attention** — the recipient lost access or safe retries were exhausted; automatic resend stops.
* **Unknown** — delivery cannot safely be assumed or repeated; automatic resend stops.
* **Superseded** — an authorized repair replaced this target without changing the workflow result.

Receipt delivery is independent of business completion. A delivery failure does not roll back the
workflow outcome, and restarting a run does not rewrite the prior attempt's receipt evidence. An
immediate in-app delivery is scheduled when a new obligation commits; the one-minute recovery scan
finds a lost schedule and due retries without rerunning workflow work.

> [!WARNING]
>
> New `outcomesV1` launches are fail-closed unless the deployment explicitly sets
> `FORGE_WORKFLOW_OUTCOMES_V1_ADMISSION=qualified-v1` after immutable qualification and the
> deployment-specific operator prerequisites are complete. Disabling new admission does not block
> callbacks, watchdog recovery, safe restart, receipt sweeps, Slack reconciliation, or repair for
> existing runs. Production activation remains disabled while the operator target, recovery owner,
> external reporting-plane monitor, live one-minute schedule, and measured drills are unresolved.

## Required outcome notifications

Workflows using outcome routing declare required operators and optional Slack destinations in
**Workflow Settings**. The run keeps the recipients for each attempt. A later settings change does
not redirect an earlier attempt's notifications. Personal notification preferences do not suppress
these required receipts.

In the run's **Flow** inspector, open **Notifications**. It lists every notification the run
recorded, on any run: these required outcome receipts and the notifications its steps send. Each is
labeled by channel (**Bell**, **Slack**, or **Email**). Select **Notification attempt** to inspect an
earlier attempt, including a notification that arrived after a restart. The panel shows its
immutable recipient, event, delivery state, retained receipt identifier, and safe error. The run
outcome remains separate from delivery status:

* **Pending** means delivery is queued or retrying; it is not a receipt.
* **Satisfied** means a personal in-app receipt exists, Slack recorded a matching channel and
  message acknowledgement, an authorized integration manager confirmed delivery in Slack
  recovery, or an email was handed to the email outbox. The outbox then owns the email's delivery
  state and retries, shown under **Platform → Email** deliveries.
* **Unknown** means Slack may have accepted the message. Open **Slack recovery** and establish what
  happened before sending again.
* **Attention** means automatic delivery cannot currently proceed. Inspect the error and repair the
  recipient or delivery operation.
* **Superseded** keeps the original destination and error and links to its replacement notification.

When a notify step records some destinations but skips others, **Recording-time skips** shows the
channel, reason, and number of skipped recipient/channel pairs once for that step and attempt on
the loaded page. Reasons include a disabled channel, denied recipient access, or an initiator or
owner who is not a person. Counts contain no skipped recipient identities and describe the first
recording decision; later provider or access changes do not rewrite them. Older receipts may have
no recorded summary. These skips have no delivery receipt or repair action. The step still succeeds
when another pair is recorded, and fails when no pair survives.

**Retry notification** requires `workflows:manage` and retries delivery only. It does
not rerun business steps or erase the original failure. In-app delivery has five bounded attempts
before operator attention. Once Slack work is enqueued, the existing Slack outbox owns retries and
rate limits; workflow repair does not start another send loop.

For a Slack operation, **Open Slack recovery** leads to the Slack provider's existing delivery
controls. Integration managers can reconcile unknown sends or requeue a rejected operation.
Return to the run to observe the same operation's updated evidence. A missing retained operation
stays in attention; it is never silently recreated.

An email notification in attention has the same **Retry notification** and **Replace recipient**
controls. A retry checks the recipient again and hands the message to the email outbox once. If the
hold came before the outbox, for example because the recipient was denied or has no email address,
fix the recipient and retry. If the outbox already rejected the message, for example because its
body is too large, the row also shows **Open email deliveries**; a retry finds that rejected
delivery and stays in attention, so replace the recipient or resolve it under **Platform → Email**.
A replacement person for an email notification is notified by email.

**Replace recipient** validates the new destination against the run's actual scope and requires a
reason. The original record is preserved. An uncertain or still-active Slack send must first be
resolved through Slack recovery. Slack workspace choices require integration management access;
an authorized in-app recipient can be selected without that grant.

Required Slack operations retain acknowledgement and uncertainty evidence, including delivered,
unknown, and rejected operations. The generic retention routines do not delete that evidence.
This feature does not enable a new garbage-collection schedule or an automatic expiry policy.

Notification repair never authorizes business replay. Preserve the run's effective verdict and
accepted provider identifiers, reconcile any `unknown` external effect first, and use targeted
restart only when the retained replay evidence says the selected boundary is safe.

## Previewing a workflow debug slice

For an immutable published version, **Debug preview** in the builder header can reconstruct the
JSON inputs that a selected node would receive from a prior run. Select a completed or failed
production run from that exact version, then select the node where inspection should begin. The
preview separates historical values that would be reused from the downstream nodes that would be
part of a future execution slice.

This surface requires both `workflows:read` and `workflows:use`, plus the
`workflow_debug_execution` feature flag. It supports linear, AI Agent-only slices with JSON boundary
values. Branching, unsupported node types, file inputs or outputs, missing historical values, and
oversized source data appear as explicit blockers.

> [!WARNING]
>
> Debug preview is data inspection only. It does not execute any node, mutate workflow state, or
> certify that the proposed slice is safe to execute.

## Exporting a run's debug bundle

The run inspector's **Export debug bundle** action collects every record needed to triage one run —
the graph snapshot, step results, validator runs, and the structured failure detail — into a single
payload. Small bundles are returned inline for copying; a bundle above the query result cap is
streamed to storage and returned as a download URL instead.

This surface requires `workflows:read`. The same permission covers the Workflow Architect's
debugger tools, which read the identical bundle when an operator asks it to explain a failed run.

## Running one current-draft node in debug

When a production run exposes a problem, edit the matching node in the workflow's current draft,
select that one `produce` or `procedure` node, and choose **Debug node** in its properties panel.
Select a completed or failed production run from the same workflow as the historical source.

Preparation is intentionally separate from execution. Before **Run debug**, review:

* the immutable target-node snapshot that will execute;
* every historical JSON and file input, including its source run, version, producer, and output key;
* the pinned agent or procedure version, tools, capabilities, credentials, and sandbox policy;
* which operations are live reads, debug-local writes, captured writes, or blocked.

Ambiguous cross-version producer names do not guess. Choose an explicit compatible historical
producer/output mapping and prepare again. Missing values, inaccessible files, incompatible types,
unclassified effects, expired plans, and unsupported human workers remain blockers.

After launch, the debug-attempt workspace shows status, logs, tool calls, structured output,
downloadable files, captured writes, the bounded written-file manifest, token and compute totals,
cost, duration, and terminal details.

The history rail shows the candidate and up to 24 earlier retained attempts for the exact same
workflow node lineage, newest first. Publishing or resetting a draft can replace the node's physical
database row without breaking that lineage, so attempts from before and after the replacement stay
in one history and remain comparable. Deleting a node and creating a new one starts a different
lineage, even when its name or configuration matches; cross-lineage comparison returns `Not found`
rather than guessing a match.

Choose **Compare** on an earlier terminal attempt to compare target configuration, inputs, effects,
outcome, metrics, files, captured writes, and tool/governance summaries. The page records the
baseline as `?compare=<baselineAttemptId>`, so a refresh or shared URL restores the same bounded
comparison while both attempts remain retained. Unchanged sections stay collapsed. A notice
identifies truncated history or comparison evidence, and an expired baseline does not hide the
candidate attempt.

**Back to draft** returns to editing. **Debug again from this setup** starts a new preparation from
the then-current draft. It reuses only the historical source run and compatible operator-selected
node-output mappings. It does not copy the old plan or plan hash, values, files, credentials,
governance decision, effects, or launch ID. Review the newly resolved plan and blockers before
launching through the normal **Run debug** control; repeat never launches automatically.

> [!WARNING]
>
> This runs one immutable snapshot of one draft node. Classified external reads may run live. External
> writes are captured without delivery or blocked, and generic captured HTTP writes return status
> `599`. Debug files and artifacts are real but remain owned by the debug attempt. The attempt never
> appears in Production Runs and does not create production completions, outcomes, counters, streams,
> or file bindings. A successful debug attempt does not prove the full production workflow will
> succeed.

This surface requires `workflows:read`, `workflows:use`, and the
`workflow_debug_execution` feature flag. Prepared plans expire after 15 minutes. Debug records and
files become cleanup-eligible after seven days.

## Key state to watch

* **Outcome** next to **Status** — a completed run can still have taken an exception or error-handling path.
* **Receipt states** — **Attention** and **Unknown** stop automatic resend and need a person to act.
* **Notification delivery** — **Unknown** on a Slack notification means open **Slack recovery** before sending again.

## Related surfaces

* [Runs](https://docs.gloo.com/forge/console/production/runs.md) — the cross-workflow run feed and the run inspector.
* [Workflows](https://docs.gloo.com/forge/console/production/workflows) — the catalog and each workflow's detail page.
* [Builder canvas](https://docs.gloo.com/forge/console/production/workflows/builder-canvas.md) — where the draft node you debug lives.
* Architecture → [Workflow Execution](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.