Troubleshooting
{"content":"{{\u003c tier level=\"sovereign\" note=\"Workflow diagnostics turn blocked automation into a clear next action.\" \u003e}}\n\nStart in the run inspector. Open **Diagnose** for the current problem and **Events** for the transition history. Select the affected step and attempt, read the visible error, then use the smallest recovery action Valdr offers.\n\n## A workflow will not save\n\n| Symptom | What to do |\n| --- | --- |\n| Validation error | Open the reported step or field and correct the value |\n| `Workflow definition '\u003ckey\u003e@\u003cversion\u003e' already exists with different content or provenance; create a new version.` | Open **Details** and change **Version**, or reload the current definition and explicitly overwrite it with matching provenance and its current content hash |\n| A pack-managed workflow needs a same-version correction | Prefer updating its source pack; a guarded overwrite must preserve pack provenance and use the current content hash |\n\n## Launch preflight fails\n\n| Error | What to do |\n| --- | --- |\n| `Required workflow input '\u003ckey\u003e' is missing.` | Correct the highlighted launch field |\n| `Agent '\u003chandle\u003e' was not found.` | Select a current registered agent |\n| `Launcher preset '\u003ckey\u003e' was not found.` | Supply a current preset to `pm_workflow start`, or correct it in the draft-test or rerun form |\n| `Workflow definition '\u003ckey\u003e' is unavailable at the requested identity.` | Refresh the catalog and choose an available version |\n| `Workflow input 'taskKey' must match the taskKey launch scope.` | Keep the locked scope values in the **Run again** dialog |\n\nA failed preflight does not start a run, so you can correct the form without cleaning up partial workflow history.\n\n## A run is waiting\n\nOpen the waiting step and check what it expects:\n\n- For agent or review work, open the linked session or review and confirm it reached the required outcome.\n- For a child workflow, open the linked child run.\n- For a human gate, review the displayed material and use the authored approval or rejection button.\n\nIf a human decision is disabled, read the denial message. Valdr reports whether the gate identity could not be verified, the gate is no longer waiting, or runtime evidence prevents submission from this view.\n\n## A preview or feedback action fails\n\n| Symptom | What to do |\n| --- | --- |\n| Preview is unavailable | Confirm the producing step completed and returned the expected document |\n| Feedback is unavailable | Confirm the workflow configured a task, review, and writer session for feedback |\n| Feedback is still running | Keep the gate open until the writer session finishes |\n| Refreshed preview fails | Reload the document before making the final decision |\n\nSending feedback does not approve or reject the gate. Review the refreshed result, then decide.\n\n## A run is blocked or failed\n\nSelect the latest attempt and review:\n\n- The error message and category.\n- Related task, session, review, or child-workflow links.\n- Prior attempts and accepted evidence.\n- Any recovery action shown by Valdr.\n\nIf **Retry step** or **Retry failed step** is unavailable, the current or latest attempt may not be failed or blocked, its error category may be unsafe to repeat, or the run may be completed or cancelled. Correct the underlying issue and use **Run again** when a separate run is the appropriate recovery. Authored `retry.maxAttempts` is a reported attempt count; it neither caps manual recovery nor schedules automatic retries or backoff.\n\nIf Valdr offers **Retry step** but cannot safely start another attempt, read the displayed reason and inspect the linked session or latest attempt for the item that still needs attention.\n\n## Run again is unavailable\n\n**Run again** is available for completed, failed, and cancelled root runs. It remains unavailable when:\n\n- You selected a child run instead of the root.\n- The run is a draft test.\n- The root is blocked; the menu says **Retry or cancel this run before running it again.**\n- The original workflow version is no longer available.\n- A required agent or launcher preset is unavailable.\n- A locked task, project, or context value was changed.\n\nRun again uses the original workflow versions. Start the newer version through `pm_workflow` when you want updated behavior.\n\n## Work continues after cancellation\n\nAn existing session referenced by a workflow may continue independently. Check [cancellation scope](/valdr/docs/workflows/reliability-and-recovery/#cancellation) before using the session or provider controls to stop remaining work.\n\n## Delete a run permanently\n\nOpen the root run's **More actions** menu and choose **Delete run** only after the root and every child are blocked, failed, completed, or cancelled. Pending, running, and waiting runs must be cancelled first. Deletion permanently removes the workflow run tree.\n\nBy default, Valdr UI also deletes linked session records, events, transcripts, and session-owned worktrees. Select **Keep linked sessions** to preserve them. This action has no restore path.\n\n## A downstream value is missing\n\n| Cause | Fix |\n| --- | --- |\n| The producing step did not declare the output | Add the named output mapping |\n| The consumer does not depend on the producer | Add the producer to `needs` |\n| The selected output is unavailable for that action | Choose a supported result in the builder |\n\nUse the producing kind's page in [Workflow Steps](../steps/) to confirm its supported inputs and outputs.\n\n## Pack import fails\n\n| Symptom | What to do |\n| --- | --- |\n| Workflow count mismatch | Regenerate the pack from the corrected source tree |\n| Duplicate workflow identity | Give each workflow key and version one definition |\n| Incoming workflow differs from the existing identity | Choose explicit `overwrite` to apply the pack version or `skip` to preserve the existing record; the default preview makes no changes |\n| Retired workflow identity | Restore that exact workflow identity before importing |\n| Missing dependency | Include or install the required workflow, capability, prompt, or agent |\n\n## Next step\n\nReturn to the [Workflow UI guide](/valdr/docs/ui/workflows/) and apply the recovery action shown for the current run.","description":"Resolve common workflow authoring, launch, wait, retry, rerun, and import problems.","title":"Troubleshooting"}
Sovereign
Sovereign tier required. Workflow diagnostics turn blocked automation into a clear next action.
Start in the run inspector. Open Diagnose for the current problem and Events for the transition history. Select the affected step and attempt, read the visible error, then use the smallest recovery action Valdr offers.
A workflow will not save
| Symptom | What to do |
|---|---|
| Validation error | Open the reported step or field and correct the value |
Workflow definition '<key>@<version>' already exists with different content or provenance; create a new version. | Open Details and change Version, or reload the current definition and explicitly overwrite it with matching provenance and its current content hash |
| A pack-managed workflow needs a same-version correction | Prefer updating its source pack; a guarded overwrite must preserve pack provenance and use the current content hash |
Launch preflight fails
| Error | What to do |
|---|---|
Required workflow input '<key>' is missing. | Correct the highlighted launch field |
Agent '<handle>' was not found. | Select a current registered agent |
Launcher preset '<key>' was not found. | Supply a current preset to pm_workflow start, or correct it in the draft-test or rerun form |
Workflow definition '<key>' is unavailable at the requested identity. | Refresh the catalog and choose an available version |
Workflow input 'taskKey' must match the taskKey launch scope. | Keep the locked scope values in the Run again dialog |
A failed preflight does not start a run, so you can correct the form without cleaning up partial workflow history.
A run is waiting
Open the waiting step and check what it expects:
- For agent or review work, open the linked session or review and confirm it reached the required outcome.
- For a child workflow, open the linked child run.
- For a human gate, review the displayed material and use the authored approval or rejection button.
If a human decision is disabled, read the denial message. Valdr reports whether the gate identity could not be verified, the gate is no longer waiting, or runtime evidence prevents submission from this view.
A preview or feedback action fails
| Symptom | What to do |
|---|---|
| Preview is unavailable | Confirm the producing step completed and returned the expected document |
| Feedback is unavailable | Confirm the workflow configured a task, review, and writer session for feedback |
| Feedback is still running | Keep the gate open until the writer session finishes |
| Refreshed preview fails | Reload the document before making the final decision |
Sending feedback does not approve or reject the gate. Review the refreshed result, then decide.
A run is blocked or failed
Select the latest attempt and review:
- The error message and category.
- Related task, session, review, or child-workflow links.
- Prior attempts and accepted evidence.
- Any recovery action shown by Valdr.
If Retry step or Retry failed step is unavailable, the current or latest attempt may not be failed or blocked, its error category may be unsafe to repeat, or the run may be completed or cancelled. Correct the underlying issue and use Run again when a separate run is the appropriate recovery. Authored retry.maxAttempts is a reported attempt count; it neither caps manual recovery nor schedules automatic retries or backoff.
If Valdr offers Retry step but cannot safely start another attempt, read the displayed reason and inspect the linked session or latest attempt for the item that still needs attention.
Run again is unavailable
Run again is available for completed, failed, and cancelled root runs. It remains unavailable when:
- You selected a child run instead of the root.
- The run is a draft test.
- The root is blocked; the menu says Retry or cancel this run before running it again.
- The original workflow version is no longer available.
- A required agent or launcher preset is unavailable.
- A locked task, project, or context value was changed.
Run again uses the original workflow versions. Start the newer version through pm_workflow when you want updated behavior.
Work continues after cancellation
An existing session referenced by a workflow may continue independently. Check cancellation scope before using the session or provider controls to stop remaining work.
Delete a run permanently
Open the root run’s More actions menu and choose Delete run only after the root and every child are blocked, failed, completed, or cancelled. Pending, running, and waiting runs must be cancelled first. Deletion permanently removes the workflow run tree.
By default, Valdr UI also deletes linked session records, events, transcripts, and session-owned worktrees. Select Keep linked sessions to preserve them. This action has no restore path.
A downstream value is missing
| Cause | Fix |
|---|---|
| The producing step did not declare the output | Add the named output mapping |
| The consumer does not depend on the producer | Add the producer to needs |
| The selected output is unavailable for that action | Choose a supported result in the builder |
Use the producing kind’s page in Workflow Steps to confirm its supported inputs and outputs.
Pack import fails
| Symptom | What to do |
|---|---|
| Workflow count mismatch | Regenerate the pack from the corrected source tree |
| Duplicate workflow identity | Give each workflow key and version one definition |
| Incoming workflow differs from the existing identity | Choose explicit overwrite to apply the pack version or skip to preserve the existing record; the default preview makes no changes |
| Retired workflow identity | Restore that exact workflow identity before importing |
| Missing dependency | Include or install the required workflow, capability, prompt, or agent |
Next step
Return to the Workflow UI guide and apply the recovery action shown for the current run.