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| A runtime field is unknown | Choose a supported [runtime reference](../definition-authoring/#runtime-values). Check the full path: a scalar such as `runtime.taskKey` has no nested properties |\n| A loop reference is unavailable | Keep loop references inside the repeated path. For a previous-pass decision in `when`, [capture it in a step output first](../steps/condition/#branch-on-a-previous-pass) |\n| A step or loop runtime value is rejected in workflow `outputMappings` | Map it to a step's declared output, then publish that output as the final result |\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| A provider preset 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| The form asks for a task or project target | Fill the input bound to the step's destination, or choose an appropriate **Run scope** default |\n| The selected task and project disagree | Use the task's project for that association or operation; a separate explicit step target may use another project |\n\nA failed preflight does not start a run, so you can correct the form without cleaning up partial workflow history.\n\nThe UI also checks target bindings that can be resolved from the final launch inputs. An optional input can still be needed by an action; see [task and project targets](../definition-authoring/#task-and-project-targets).\n\nLaunch checks cover declared inputs and agent or preset selections known before the run starts. A disabled or unauthenticated provider, unreachable model, incompatible worktree, busy session, or missing preset selected by an earlier step can still cause a failure after launch. Inspect the affected step's error and correct that dependency before retrying.\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\nFor a Command step, retry may offer saved command, working-directory, timeout, or environment changes. If those settings change again before you retry, refresh and review them. If saved Command settings are unavailable, restore the active saved definition at the same key and version with that Command step. To change which Session a step uses, or to change steps and dependencies, start a new run.\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 provider preset is unavailable.\n- The original run association or context was changed. Declared task and project inputs remain editable.\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| The producer was skipped by a `when` check | Give the consumer matching branch conditions; a skipped dependency supplies no outputs |\n| An exact array or Boolean became text | Use the reference alone, without surrounding text, to preserve its type |\n| A prior-loop output is missing on pass 1 | This is expected: there is no previous decision yet. Handle the first pass explicitly; a prior-decision branch can skip until the next pass |\n| A runtime task/project value is `null` | Choose a run association when the step should use it, or supply an explicit action target |\n| Interpolated text hides a missing value | Inspect the producing attempt's outputs. Missing or `null` values add an empty string, so text such as `prior:` alone does not prove a prior decision exists |\n\nUse the producing kind's page in [Workflow Steps](../steps/) to confirm its supported inputs and outputs.\n\n## A user tool is unavailable or fails\n\n| Symptom | What to do |\n| --- | --- |\n| Tool is missing from the Builder | Find it in **Workflows \u003e Tools** and clear the filter. If its card shows **Unavailable**, open it to read the reason. If there's no card, the revision was removed from the catalog or never imported. The Builder also leaves out a tool whose actions are all unsupported |\n| An older tool revision is missing from the Tools grid | Enable **Show all versions**; the default view shows only the newest installed revision per tool |\n| Action is unsupported | Read the reason shown in the catalog; a listed CLI command isn't necessarily implemented |\n| Missing executable | Install the runtime or CLI on the workflow host and make sure it's on the `PATH` Valdr runs with |\n| Wrong working directory | Check the workflow session worktree or project repository and the optional step-level `cwd` override; `cwd` is not an action input |\n| Tool shows **Unavailable** because installed files were changed or removed | Don't edit installed copies. Re-importing the same revision doesn't repair them: bump the revision in the reviewed source, then package and import it, and select the new revision in affected workflows |\n| Input or output schema failure | Read the schema error in **Runs**. Compare the step's inputs, or your program's `data`, with the action's schemas in the pinned revision, and rerun the program's direct test to see its full result |\n| Timeout or byte limit | Reduce the work or output, or raise `timeoutSeconds` or `maxResultBytes` in a new revision, within the host maximum. Check for external effects before retrying |\n| The failure is titled **needs attention** and **Retry step** isn't offered | Valdr can't tell whether the tool already changed something. Check the external system and reconcile what happened, then cancel the run and start a new one if the work still needs to happen |\n\nA failed step doesn't fill its output mappings. See [User Tools](../steps/user-tool/) and [uncertain outcomes](../reliability-and-recovery/#user-tool-attempts-and-uncertain-outcomes).\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 |
| A runtime field is unknown | Choose a supported runtime reference. Check the full path: a scalar such as runtime.taskKey has no nested properties |
| A loop reference is unavailable | Keep loop references inside the repeated path. For a previous-pass decision in when, capture it in a step output first |
A step or loop runtime value is rejected in workflow outputMappings | Map it to a step’s declared output, then publish that output as the final result |
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 |
| A provider preset 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 |
| The form asks for a task or project target | Fill the input bound to the step’s destination, or choose an appropriate Run scope default |
| The selected task and project disagree | Use the task’s project for that association or operation; a separate explicit step target may use another project |
A failed preflight does not start a run, so you can correct the form without cleaning up partial workflow history.
The UI also checks target bindings that can be resolved from the final launch inputs. An optional input can still be needed by an action; see task and project targets.
Launch checks cover declared inputs and agent or preset selections known before the run starts. A disabled or unauthenticated provider, unreachable model, incompatible worktree, busy session, or missing preset selected by an earlier step can still cause a failure after launch. Inspect the affected step’s error and correct that dependency before retrying.
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.
For a Command step, retry may offer saved command, working-directory, timeout, or environment changes. If those settings change again before you retry, refresh and review them. If saved Command settings are unavailable, restore the active saved definition at the same key and version with that Command step. To change which Session a step uses, or to change steps and dependencies, start a new run.
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 provider preset is unavailable.
- The original run association or context was changed. Declared task and project inputs remain editable.
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 |
The producer was skipped by a when check | Give the consumer matching branch conditions; a skipped dependency supplies no outputs |
| An exact array or Boolean became text | Use the reference alone, without surrounding text, to preserve its type |
| A prior-loop output is missing on pass 1 | This is expected: there is no previous decision yet. Handle the first pass explicitly; a prior-decision branch can skip until the next pass |
A runtime task/project value is null | Choose a run association when the step should use it, or supply an explicit action target |
| Interpolated text hides a missing value | Inspect the producing attempt’s outputs. Missing or null values add an empty string, so text such as prior: alone does not prove a prior decision exists |
Use the producing kind’s page in Workflow Steps to confirm its supported inputs and outputs.
A user tool is unavailable or fails
| Symptom | What to do |
|---|---|
| Tool is missing from the Builder | Find it in Workflows > Tools and clear the filter. If its card shows Unavailable, open it to read the reason. If there’s no card, the revision was removed from the catalog or never imported. The Builder also leaves out a tool whose actions are all unsupported |
| An older tool revision is missing from the Tools grid | Enable Show all versions; the default view shows only the newest installed revision per tool |
| Action is unsupported | Read the reason shown in the catalog; a listed CLI command isn’t necessarily implemented |
| Missing executable | Install the runtime or CLI on the workflow host and make sure it’s on the PATH Valdr runs with |
| Wrong working directory | Check the workflow session worktree or project repository and the optional step-level cwd override; cwd is not an action input |
| Tool shows Unavailable because installed files were changed or removed | Don’t edit installed copies. Re-importing the same revision doesn’t repair them: bump the revision in the reviewed source, then package and import it, and select the new revision in affected workflows |
| Input or output schema failure | Read the schema error in Runs. Compare the step’s inputs, or your program’s data, with the action’s schemas in the pinned revision, and rerun the program’s direct test to see its full result |
| Timeout or byte limit | Reduce the work or output, or raise timeoutSeconds or maxResultBytes in a new revision, within the host maximum. Check for external effects before retrying |
| The failure is titled needs attention and Retry step isn’t offered | Valdr can’t tell whether the tool already changed something. Check the external system and reconcile what happened, then cancel the run and start a new one if the work still needs to happen |
A failed step doesn’t fill its output mappings. See User Tools and uncertain outcomes.
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.