Workflow Pauses

Workflow Pauses are human-in-the-loop checkpoints created by a Pause block. They let a run record a message, stop at a specific node, and wait for a decision before later work is attempted.

Prerequisites

• Use a Starter or higher workspace.
• Use a workspace owner for the supported Workflows navigation and write actions.
• Deploy a workflow containing a configured Pause block.
• Make the checkpoint message specific enough for a reviewer to make a safe decision.

Wait and Pause Are Different

Both can put an execution in Waiting, so always inspect the current node.

Configure a Pause Block

In Workflow Studio, add Pause, select it, and open Editor.

• Message is the context displayed to the reviewer.
• Resume Key is an optional key used by the worker resume endpoint.
• Timeout (seconds) is optional and must be at least 60 seconds when provided.

Leave Resume Key empty for ordinary web-managed checkpoints. The worker then generates a unique UUID for each pause. A configured fixed key is unique at the database level; reusing the same value across multiple executions can resolve to an earlier checkpoint instead of creating a new one.

Connect the Pause block to the next block, save, validate, and deploy the workflow.

Open Workflow Pauses

The Workflows section has only Workflows and Executions tabs. To open the pause dashboard:

1. Open Workflows → Executions.
2. Select a waiting run.
3. In Action Required, choose View All Pauses.

You can also act on a pending pause directly from Action Required in Execution Details.

Read the Dashboard

The summary cards are:

• Pending Action from an exact pending-count query,
• Resumed from up to 100 resumed records,
• Expired from up to 100 expired records, and
• Total from up to 100 records of any state.

The All Pauses list loads up to 50 records by default. Pending records are sorted first, then newer records. Use Search pauses... to match node ID, message, execution ID, or workflow-definition ID. Use All Statuses to choose Pending, Resumed, Expired, or Canceled.

These cards and lists are operational summaries, not an unlimited audit export.

Pause States

The card can show an Expires timestamp. Treat the timestamp and execution state as separate facts from the badge.

Review Pause Details

Select a card or choose Resume to open Pause Details. The modal includes:

• status and expiry,
• workflow-definition ID,
• execution ID,
• node ID,
• resume key,
• created and resumed timestamps, and
• the checkpoint message.

For pending checkpoints, Resume Payload (Optional) accepts a JSON object. Invalid JSON is rejected in the browser.

Example:

{
  "approved": true,
  "notes": "Approved after invoice review"
}

Do not enter secrets. Runtime context can appear as raw JSON on the execution page.

Current Web Resume Behavior

The current Resume Workflow web action:

• requires the checkpoint to still have status pending,
• marks the checkpoint resumed, and
• records the resumed timestamp.

It currently does not enqueue the worker resume job, and it accepts but does not persist or merge the optional payload. The separate worker resume endpoint does enqueue continuation and merge payload, but the current web modal is not connected to that operation.

For that reason, the success toast Workflow resumed successfully proves the checkpoint update succeeded; it does not prove the execution continued.

After choosing Resume Workflow:

1. Return to Execution Details.
2. Refresh the page.
3. Confirm the execution moves from Waiting to Running or Completed.
4. Confirm a resumed step appears in Execution Replay.
5. If it remains Waiting, preserve the execution ID and resume key and contact support or a self-hosted operator who can use the worker resume endpoint.

Current Timeout Behavior

The Pause editor describes timeout as auto-expiration. In the current engine, the timeout also becomes the execution’s scheduled resume time. The waiting-resume sweep runs every two minutes and can enqueue continuation after that time; the resume job then marks pending records Resumed.

By contrast, the worker resume endpoint marks a checkpoint Expired when someone calls it after the expiry. The current web action does not perform that expiry check.

The result is that a passed wall-clock expiry does not guarantee the dashboard already says Expired. Verify the execution’s current state and replay before deciding whether work is still blocked.

Cancel a Pause

Choose Cancel Pause only when the checkpoint record itself should be closed. The action changes a pending pause to Canceled.

It does not:

• cancel the execution,
• advance the execution to the next block, or
• create a replacement run.

If the execution must stop, use Stop while the editor is tracking that run or use an authorized execution-cancel integration. If the execution should continue, resolve the resume path instead of canceling the checkpoint.

Idempotency and Concurrency

• A generated resume key is unique per checkpoint.
• The worker resume endpoint returns an already-resumed, expired, or canceled terminal response instead of queueing a second resume for those states.
• The web action rejects any checkpoint that is no longer pending.
• The worker resume job row-locks the execution and skips a run that is no longer resumable.
• A waiting run will not resume while its workflow definition is inactive.

Troubleshooting

Resume Payload says invalid JSON

Enter one JSON object with quoted property names. Arrays, comments, and trailing commas are not accepted by the current form contract.

Resume succeeded but the execution is still Waiting

This matches the current web-wiring gap. Refresh Execution Details, then escalate with the execution ID, node ID, and resume key. Do not repeatedly click Resume; the pause is no longer pending.

Cancel Pause did not cancel the run

Canceling a checkpoint and canceling an execution are different operations. The current pause button only changes the checkpoint record.

A pause shows Expires in the past but still says Awaiting Action

Status is persisted; it is not derived in the browser from the current clock. Refresh and inspect the execution. The resume endpoint, scheduled continuation, and current web action handle expiry differently.

Creating the pause did not produce a new card

Check that the workflow was active, the execution reached the Pause node, and the Resume Key was not reused. Open the run’s replay to confirm the current node.

Resume was skipped after deactivation

Resume jobs require the workflow definition to remain active. Reactivate only after reviewing the current definition and waiting execution; major node or edge changes can make continuation unsafe.

Related Docs

• Workflows
• Workflow Executions
• Build Your First Workflow
• Monitor and Recover Workflows