How Do I Debug a Stuck or Failed Instance in Dave by voolama?

Summary

The steps

1. 1

   Identify the status and open the instance detail page

   Navigate to Instances in the sidebar. Find the instance in the list. Read the color-coded status badge in the Status column. The badge tells you which diagnostic path to follow.

   Badge color	Status	Diagnostic path
   Amber	waiting_user_input	Step 2: find and complete the pending User Interaction task
   Pink	waiting_review	Step 3: find and complete the pending Human Review task
   Red	failed	Step 4: read the context viewer and tasks table for the error
   Amber	paused	Step 5: decide whether to resume or cancel

   Click the instance row to open the instance detail page. The detail page shows the Instance ID (monospaced text below the heading), the status badge (top-right), control buttons (Start, Pause, Resume, Cancel, depending on status), a metadata grid with Created, Started, and Completed timestamps, a tasks table, and the context viewer. Sourced from the instances help documentation, DEV v0.11.0, confirmed against content_orchestrator main at commit ddb945f, 2026-08-30.

   Do this

   • Navigate to Instances in the sidebar.
   • Read the status badge color: amber (waiting_user_input or paused), pink (waiting_review), red (failed).
   • Click the instance row to open the detail page.
   • Note the Instance ID for reference when checking the tasks table or contacting support.

   Example

   An instance shows an amber badge labeled waiting_user_input. You click the row. The detail page opens. The status badge in the top-right confirms waiting_user_input. The Started timestamp shows a time two hours ago. The Completed timestamp shows a dash, meaning the instance has not finished. The tasks table shows one row with a clock icon (pending) in the Status column. Proceed to step 2. Verify: the clock icon is independently observable. No vendor trust required.

   Best practice

   The instances help documentation states: 'Monitor waiting states: if an instance is in waiting_user_input or waiting_review, check the tasks table for pending tasks that need your attention. The instance will not proceed until those tasks are completed.' Check the Instances list at the start of each working session. A waiting instance does not generate alerts by default: it waits silently until a human acts.

2. 2

   Resolve waiting_user_input: find and complete the pending task

   waiting_user_input (amber) means the instance has reached a User Interaction node. A task has been created and is waiting in a user's inbox. The instance will not proceed until the task is submitted. Sourced from the instances help documentation, DEV v0.11.0, confirmed 2026-08-30.

   On the instance detail page, find the tasks table. Look for a row with a clock icon (pending) in the Status column and a type of user_interaction. Click the Type link to open the task detail page. Complete the required input and submit. The instance status changes from waiting_user_input to running automatically.

   Do this

   • On the instance detail page, scroll to the tasks table.
   • Find the row with a clock icon and type user_interaction.
   • Click the Type link to open the task detail page.
   • Complete the required input and submit.
   • Return to the instance detail page. Confirm the status badge has changed from waiting_user_input to running or completed.

   Example

   The tasks table shows one pending user_interaction task created at 09:14. You click the Type link. The task detail page opens with a text input field and a Submit button. You enter the required data and click Submit. You return to the instance detail page. The status badge now shows running (green). Thirty seconds later it changes to completed (blue). Verify: the Completed timestamp in the metadata grid is now populated. No vendor trust required.

   Best practice

   See Work a Task from Your Inbox for the full task completion path. If the task is assigned to a specific user and that user is unavailable, an Admin can reassign the task at Admin, then Tasks. Only users with the Use role can be assigned tasks: if the intended reviewer lacks the Use role, the task will not appear in their inbox.

3. 3

   Resolve waiting_review: find and complete the pending Human Review task

   waiting_review (pink) means the instance has reached a Human Review node. A review task has been created and is waiting for a reviewer to vote Approve or Reject. The instance will not proceed until the vote is recorded. Sourced from the instances help documentation, DEV v0.11.0, confirmed 2026-08-30.

   On the instance detail page, find the tasks table. Look for a row with a clock icon (pending) in the Status column and a type of human_review or agent_review. Click the Type link to open the task detail page. Vote Approve or Reject. The instance resumes automatically.

   Do this

   • On the instance detail page, scroll to the tasks table.
   • Find the row with a clock icon and type human_review or agent_review.
   • Click the Type link to open the task detail page.
   • Read the content to review. Vote Approve or Reject.
   • Return to the instance detail page. Confirm the status badge has changed from waiting_review to running or the next waiting state.

   Example

   The tasks table shows one pending human_review task created at 14:32. The Node column shows node-07. You click the Type link. The task detail page opens showing the AI-generated draft and two buttons: Approve and Reject. You click Approve. You return to the instance detail page. The status badge changes from waiting_review (pink) to running (green). Verify: the task row in the tasks table now shows a checkmark icon instead of a clock. No vendor trust required.

   Best practice

   If no reviewer has the task in their inbox, check their role. Only users with the Use role can be assigned tasks. An Admin can view all pending tasks at Admin, then Tasks, and reassign them. The instances help documentation states: 'A review task is pending in the tasks table.' The tasks table on the instance detail page always shows the current task status, regardless of who the task is assigned to.

4. 4

   Diagnose a failed instance: read the context viewer and tasks table

   failed (red) means the instance encountered an error it could not recover from. No further tasks will be generated. The instance cannot be restarted: you must create a new instance after fixing the root cause. Sourced from the instances help documentation, DEV v0.11.0, confirmed 2026-08-30.

   Two diagnostic tools are available on the instance detail page: the tasks table and the context viewer. The instances help documentation states: 'Check the tasks table and context viewer for details.'

   Tool 1: Tasks table. Find the row with an X icon (failed) in the Status column. The Node column shows the graph node ID where the failure occurred. The Type column shows the task type (for example, agent_interaction). This tells you which node failed.

   Tool 2: Context viewer. Click Context with the right-pointing arrow to expand the context viewer. The contextHead renders as formatted JSON. When a node fails, it writes its error details and stack trace to the contextHead. Read the error message. Three root causes account for the majority of failed instances, each with a specific fix:

   Error in contextHead	Root cause	Fix
   No agent assigned or similar	Missing agent assignment on an agent_interaction node	Open the workflow in the Workflow Editor. Find the node ID from the tasks table. Assign an agent to the node. Save a new workflow version. Create a new instance from the new version.
   Invalid edge or routing error	Invalid edge rules in the workflow graph	Open the workflow in the Workflow Editor. Check the Routing node connected to the failed node. Fix the edge condition. Save a new workflow version. Create a new instance.
   Provider not responding or timeout	AI provider is not reachable or the API key is invalid	Navigate to Admin, then API Management, then Providers. Check the provider status indicator. Re-enter the API key if needed. Retry the instance by creating a new one from the same workflow version.

   Do this

   • On the instance detail page, scroll to the tasks table. Find the row with an X icon. Note the Node ID and task Type.
   • Scroll to the context viewer. Click Context with the right-pointing arrow to expand it.
   • Read the error message in the contextHead JSON.
   • Match the error to one of the three root causes in the table above.
   • Apply the fix: correct the workflow in the Workflow Editor, or fix the provider configuration.
   • Create a new instance from the corrected workflow version. Do not attempt to restart the failed instance: it cannot be restarted.

   Example

   The tasks table shows one failed (X icon) task of type agent_interaction at node node-04. You expand the context viewer. The contextHead JSON contains: {"error": "No agent assigned to node node-04", "nodeId": "node-04", "status": "failed"}. Root cause: missing agent assignment. Fix: navigate to Workflows, open the workflow, open the Workflow Editor, find node-04, assign an agent, save a new version. Create a new instance from the new version. Verify: the new instance progresses past node-04 without failing. No vendor trust required.

   Best practice

   See Watch a Run and Read Its Timeline for the full instance monitoring path. The instances help documentation states: 'When the engine recovers stuck instances after a restart, recovery events are logged.' If an instance failed during a platform maintenance window, the audit log (Admin, then Settings, then Audit Log) will show a crash recovery event with a timestamp. Check the audit log before assuming the failure is a configuration error.

5. 5

   Decide whether to pause, resume, or cancel a paused instance

   paused (amber) means execution was manually suspended. The instance is not waiting on a task: it was stopped by a user clicking Pause. No new tasks are generated while paused. The instance can be resumed at any time by clicking Resume. Sourced from the instances help documentation, DEV v0.11.0, confirmed 2026-08-30.

   The instances help documentation states: 'Pause temporarily suspends execution. Cancel permanently terminates the instance and it moves to cancelled status and cannot be restarted. Use pause when you want to investigate; use cancel when you want to stop entirely.'

   The control buttons available on a paused instance are Resume and Cancel. Resume transitions the instance back to running. Cancel transitions it to cancelled (gray), a terminal state with no further action possible.

   Do this

   • On the instance detail page, confirm the status badge shows paused (amber).
   • Expand the context viewer to inspect the contextHead. Determine whether the instance data looks correct up to the point it was paused.
   • If the data looks correct and you want to continue: click Resume. The instance transitions to running.
   • If the data is incorrect or the workflow has a configuration error: do not resume. Click Cancel. Fix the workflow in the Workflow Editor. Create a new instance from the corrected version.

   Example

   An instance was paused during a review of its output. You open the detail page. The context viewer shows the contextHead with the AI-generated draft in the draft_copy field. The draft looks correct. You click Resume. The status badge changes from paused (amber) to running (green). The next node activates and a new task appears in the tasks table. Verify: the tasks table shows a new pending task with a clock icon. No vendor trust required.

   Best practice

   The instances help documentation states: 'Pause instead of cancel when uncertain: if something looks wrong but you are not sure, pause the instance first. You can resume a paused instance, but cancellation is permanent.' Only Admin and Use roles can pause, resume, or cancel instances. Dave by voolama has six default roles: Admin, Create, Curate, Use, Reporting, and Financial. Roles are editable. If a team member cannot see the Resume or Cancel button, their role does not include instance control permissions.

What this guide does not cover