How to Debug a Stuck Workflow Instance

Summary

The steps

1. 1

   Open the instance list and locate the stuck instance

   Navigate to Instances in the sidebar. The instance list shows every instance in your tenant with a color-coded status badge, the workflow version it is running, the owner, and the creation date.

   Look for instances in any of these statuses, which indicate the instance is not progressing on its own:

   • waiting_user_input (amber): the instance has reached a node that requires human input and is waiting for a task to be completed.
   • waiting_review (pink): the instance has reached a human review node and is waiting for a reviewer to act.
   • paused (amber): execution was manually suspended. The instance will not proceed until someone clicks Resume.
   • failed (red): the instance encountered an unrecoverable error and has stopped.
   • running (green) with no recent progress: the instance is technically in a running state but tasks may be stalled or an agent call may be hanging.

   Click the status badge or the instance row to open the instance detail page.

   Do this

   • Go to Instances in the sidebar.
   • Scan the Status column for amber, pink, or red badges.
   • Click the row of the instance you want to investigate.

   Example

   You see an instance with a pink waiting_review badge that was created two days ago. The workflow is a contract review process that normally completes within a few hours. This instance is the one to investigate.

   Best practice

   Check the instance list at the start of each working day if you operate time-sensitive workflows. An instance that has been in waiting_user_input or waiting_review for longer than your expected turnaround time is a signal that a task has been missed or mis-assigned. The Pending Tasks card on the Dashboard gives you a tenant-wide count without needing to scan the full instance list.

2. 2

   Read the status badge and control buttons on the detail page

   The instance detail page opens with the instance ID in monospaced text below the heading and a color-coded status badge in the top right. The control buttons displayed depend on the current status and tell you immediately what actions are available.

   Use this table to interpret what you see:

   • draft (gray): the instance was created but never started. Buttons: Start, Cancel. This is not a stuck instance; it was never run.
   • running (green): Buttons: Pause, Cancel. If the instance appears to be making no progress, check the tasks table in Step 3 for a pending task that has not been picked up.
   • paused (amber): Buttons: Resume, Cancel. Someone paused this instance. Click Resume if you are ready to continue, or investigate the tasks and context first.
   • waiting_user_input (amber): Button: Cancel only. A User Interaction task is pending. The instance cannot proceed until that task is completed. Go to Step 3.
   • waiting_review (pink): Button: Cancel only. A Human Review task is pending. Go to Step 3.
   • failed (red): No buttons. The instance has stopped. Go to Step 4 to inspect the context and tasks for error details.
   • completed or cancelled (blue/gray): No buttons. These are terminal states. The instance is not stuck; it finished or was stopped.

   Also check the metadata grid below the control buttons. The three cards show the Created, Started, and Completed timestamps. If Started shows a timestamp but Completed shows a dash, the instance started but has not finished. The gap between Started and now tells you how long it has been running.

   Do this

   • Read the status badge color and label in the top right of the detail page.
   • Note which control buttons are visible: this tells you what transitions are available.
   • Check the metadata grid: note the Started timestamp and whether Completed is still showing a dash.
   • If the status is paused and you are ready to continue, click Resume. Otherwise proceed to Step 3.

   Example

   The instance shows a pink waiting_review badge. The only button available is Cancel. The metadata grid shows it was Started 47 hours ago and Completed is still a dash. You know a review task is pending somewhere and no one has acted on it.

   Best practice

   If you are unsure whether to resume or cancel, use Pause first (available on running instances) to freeze the instance while you investigate. A paused instance can be resumed; a cancelled instance cannot be restarted. Reserve Cancel for instances where you have confirmed the run should be abandoned entirely.

3. 3

   Find the blocking task in the tasks table

   Scroll down to the Tasks table on the instance detail page. This table lists every task the instance has generated, with four columns: Type (linked to the task detail page), Status (with icon indicators), Node (the graph node ID that generated the task), and Created (timestamp).

   Look for tasks with a pending status indicator. These are the tasks that have not been completed and are blocking the instance from progressing.

   The task type tells you what kind of action is required:

   • user_interaction: a human needs to provide input. The instance is in waiting_user_input.
   • human_review: a human needs to review AI output and make a decision (Approve, Reject, or Request Changes). The instance is in waiting_review.
   • agent_interaction: an AI agent was called. If this task shows a failed status, the agent or provider call did not succeed.
   • agent_review: an agent was called to review another agent's output. A failed status here indicates a configuration or provider issue.
   • safety_check: a safety evaluation node ran. A failed status here may indicate the content was flagged or the safety provider did not respond.

   Click the Type link on the pending or failed task to open the task detail page. The task detail shows the full payload (the data passed to the task from the workflow context), the decision panel (for human tasks), and the submitted result (for completed tasks). For a failed agent task, the payload and any error information captured by the engine will be visible here.

   Do this

   • Scroll to the Tasks table on the instance detail page.
   • Identify any tasks with a pending or failed status icon.
   • Note the task Type and the Node ID to understand where in the workflow graph the instance is stuck.
   • Click the Type link on the pending or failed task to open the task detail page.
   • For a pending human task: complete the required action (provide input, or submit Approve, Reject, or Request Changes).
   • For a failed agent task: note the error details visible in the task payload and proceed to Step 4.

   Example

   The tasks table shows three tasks. The first two have a checkmark (completed). The third is a human_review task with a pending icon, created 47 hours ago, on node review-contract-output. You click through to the task detail, see the AI-drafted contract summary in the payload, and submit an Approve decision. The instance immediately transitions from waiting_review back to running.

   Best practice

   If a human task has been pending for longer than expected, check who the task is assigned to. The task detail page shows the Assignee. If the assignee is unavailable, an Admin user can reassign the task or complete it directly. Unassigned or mis-assigned tasks are the most common reason a workflow sits in waiting_review or waiting_user_input for days without progressing.

4. 4

   Inspect the context viewer for error details

   If the instance is in a failed state, or if a task has failed and you want to understand what the instance knew at that point, expand the Context section on the instance detail page. Click Context ▸ to expand it. The context viewer renders the instance's contextHead as formatted JSON.

   The context is a JSON object that accumulates data as the instance moves through nodes. Each node reads from and writes to the context, so the context head at the point of failure reflects everything the instance had processed up to that moment. This is the primary debugging surface for a failed instance.

   Look for these signals in the context JSON:

   • Error fields: the engine may write error messages or failure reasons into the context when a node fails. Look for keys such as error, errorMessage, or failureReason. The exact key names depend on how the workflow was built.
   • Missing expected fields: if a node was supposed to write a value to the context and the key is absent, the node did not complete successfully. Compare the context against what you expect the workflow to have produced at each step.
   • Unexpected values: if a field is present but contains an unexpected value (for example, an empty string where a contract clause should be, or a null where an agent response should be), the agent call may have returned an empty or malformed response.

   Cross-reference what you find in the context with the failed task in the tasks table. The task detail page shows the payload that was passed to the task, and the context shows what the instance accumulated before and after. Together they give you a complete picture of what the engine attempted and what it received back.

   Do this

   • On the instance detail page, click Context ▸ to expand the context viewer.
   • Read the JSON carefully. Look for error keys, missing fields, or unexpected values.
   • Cross-reference with the failed task's payload on the task detail page.
   • Note the node ID of the failed task (from the tasks table) and find the corresponding node in the Workflow Editor to check its configuration.

   Example

   The context viewer shows a key agentResponse with a value of null. The failed task is an agent_interaction on node extract-clauses. This tells you the agent call returned nothing. The likely causes are a provider configuration issue, an invalid API key, or a model that is no longer available at the configured provider.

   Best practice

   The context viewer is the fastest way to understand what an instance knew at the point of failure. Get into the habit of expanding it whenever an instance fails, even if the cause seems obvious from the task status. The context often contains information that clarifies whether the problem is in the workflow design, the agent configuration, or the provider connection, and that distinction determines the correct fix.

5. 5

   Identify the root cause and apply the fix

   With the status, tasks table, and context in hand, you can now identify which of the three root causes applies and take the appropriate action.

   Root cause 1: a human task was not completed. The instance is in waiting_user_input or waiting_review and a task is pending in the tasks table. Fix: open the task detail page and complete the task. The instance will resume automatically once the task is submitted. No changes to the workflow or agent are needed.

   Root cause 2: an agent or provider call failed. The instance is in failed status, a task of type agent_interaction or agent_review has a failed status, and the context shows a null or error value for the agent's output. Fix: navigate to Admin, then API Management, then Providers and verify the provider configuration: check that the API key is still valid, the base URI is correct, and the provider is reachable. If the provider is correctly configured, check the agent's model selection in Agents: the model name may have changed or been deprecated by the provider. Once the provider or agent is corrected, create a new instance of the same workflow version to re-run the process. A failed instance cannot be restarted; it must be re-created.

   Root cause 3: a workflow graph configuration error. The instance failed immediately after starting, or failed at a routing or transition step rather than at an agent node. The context may show an error related to edge conditions or node configuration. Fix: navigate to the Workflow Editor for the workflow version this instance was running. Check the node identified in the failed task's Node column. Look for missing required fields, invalid edge conditions, or a node that references an agent or provider that no longer exists. Save a corrected version of the workflow, then create a new instance from the corrected version.

   Do this

   • Match your findings from Steps 2, 3, and 4 to one of the three root causes above.
   • For a pending human task: complete it on the task detail page. The instance resumes automatically.
   • For a failed agent call: check the provider at Admin, then API Management, then Providers. Verify the API key and base URI. Check the agent's model selection in Agents. Create a new instance once the configuration is corrected.
   • For a graph configuration error: open the Workflow Editor, locate and fix the misconfigured node, save a new version, and create a new instance from the corrected version.

   Example

   The context showed agentResponse: null on the extract-clauses node. You navigate to Admin, then API Management, then Providers and find the OpenAI provider's API key was rotated last week but not updated in DAVE. You enter the new key, save the provider, and create a new instance of the same workflow version. The new instance runs to completion.

   Best practice

   When a failed instance reveals a provider or agent configuration problem, check whether other workflows in your tenant use the same provider or agent. A single misconfigured provider can cause failures across multiple workflows simultaneously. Fix the root cause at the provider or agent level, not just for the one instance you are debugging.

6. 6

   Cancel or retain the original failed instance

   Once you have resolved the root cause and created a new instance if needed, decide what to do with the original stuck or failed instance.

   A failed instance is already in a terminal state: no further action is required to stop it. It will remain in the instance list in failed status until your tenant's retention policy removes it. You do not need to cancel it.

   A paused instance that you have decided not to resume should be cancelled explicitly. Click Cancel on the instance detail page. The instance moves to cancelled status. This is permanent: a cancelled instance cannot be restarted.

   A waiting_user_input or waiting_review instance where the task has now been completed will resume automatically. You do not need to take any additional action on the instance itself.

   Retain failed instances for as long as your debugging and compliance needs require. The context viewer and tasks table remain accessible on a failed instance, so you can return to it later if you need to reconstruct what happened. Your tenant's audit log also records all state transitions, step executions, error events, and crash recovery events for every instance, providing a complete timeline independent of the instance detail page.

   Do this

   • If the instance is failed: no action needed to stop it. It is already terminal. Retain it for reference or let the retention policy clean it up.
   • If the instance is paused and you are abandoning it: click Cancel on the detail page.
   • If the instance was in waiting_user_input or waiting_review and you completed the task: the instance resumes automatically. Monitor the status badge to confirm it returns to running.
   • Check the audit log for a full timeline of the instance's state transitions and error events.

   Example

   The original failed instance remains in the list in red failed status. You leave it in place for 30 days so the team can refer to the context if a similar failure occurs. The new instance you created runs to completion and shows a blue completed badge. You confirm the fix worked.

   Best practice

   Document what you found and what you fixed, even briefly. A failed instance caused by a rotated API key will cause the same failure again the next time a key is rotated, unless the team knows to check DAVE's provider configuration as part of the key rotation process. A short internal note connecting the failure to the fix is worth more than any amount of post-incident debugging.

What this guide covers and when to use it

Understanding the statuses that indicate a stuck instance

The context viewer as a debugging tool

Frequently asked questions