Skip to main content

Troubleshooting tasks

When a task fails, start by checking the rendered inputs and outputs. Most issues come from templating, missing context, or overly broad instructions.

Check rendered instructions​

Open the run view and look at the rendered instructions for each agent. If a template resolves to an empty value or the wrong file path, fix the template before retrying.

Inspect outputs and errors​

Every step has an output, even on failure. Use outputs.<step> and errors.<step> in a follow-up prompt to summarize what happened.

steps:
  - id: summarize_failures
    prompt: |
      Failures: {{ errors.fix_step | json_encode(pretty=true) }}
      Output: {{ outputs.fix_step | json_encode(pretty=true) }}

starts_with: summarize_failures
edges: []

Common failure modes​

  • run exits with a non-zero status.
  • structured_prompt fails schema validation.
  • agent fails to follow constraints or cannot complete the task.
  • Templates reference missing inputs, outputs, or for_each values.
  • The agent lacks access to needed tools or repo paths.

Add a narrow debug step​

Add a small run step to confirm the working directory and list files. This helps you rule out path issues.

steps:
  - id: debug_workspace
    name: Debug workspace
    run: |
      pwd
      ls -la

starts_with: debug_workspace
edges: []

Retry with smaller scope​

  • Limit inputs so the workflow touches fewer files.
  • Use for_each to isolate the failing item.
  • Enable continue_on_error: true to collect failures without stopping the run.