Troubleshooting¶

Common issues and how to resolve them.

Workflow Validation Errors¶

"unknown agent: X"¶

Problem: A step references an agent that isn't defined.

Error: unknown agent 'security-reviewer' referenced in step 'scan'

Solution: Check spelling and define the agent:

agents:
  security-reviewer:  # Must match exactly
    inline:
      description: "..."
      prompt: "..."

steps:
  - id: scan
    agent: security-reviewer  # Must match agents section

"circular dependency detected"¶

Problem: Steps depend on each other in a loop.

Error: circular dependency detected: step-a -> step-b -> step-a

Solution: Review your depends_on chains and break the cycle:

# ✗ Bad: Circular
- id: step-a
  depends_on: [step-b]
- id: step-b
  depends_on: [step-a]

# ✓ Good: Linear
- id: step-a
- id: step-b
  depends_on: [step-a]

"duplicate step id: X"¶

Problem: Two steps have the same ID.

Error: duplicate step id 'analyze'

Solution: Give each step a unique ID:

steps:
  - id: analyze-security  # Unique
    ...
  - id: analyze-performance  # Unique
    ...

"missing required input: X"¶

Problem: An input without a default wasn't provided.

Error: missing required input: files

Solution: Either provide the input or add a default:

# Option 1: Provide at runtime
goflow run --workflow example.yaml --inputs files='src/*.go'

# Option 2: Add default
inputs:
  files:
    description: "Files to analyze"
    default: "*.go"  # Now optional

Runtime Errors¶

"step X failed: context deadline exceeded"¶

Problem: A step exceeded its configured timeout limit.

Event-Based Completion

goflow uses event-based session monitoring by default — sessions complete naturally when the LLM finishes. You only see this error if you explicitly set a timeout on the step.

Solutions:

Remove the timeout — If you don't need a strict time limit, remove the timeout field and let the session complete naturally

Increase the timeout — If you need a safety limit, increase it:

steps:
  - id: long-analysis
    agent: analyzer
    prompt: "..."
    timeout: "10m"  # More time for complex tasks

Use --verbose or --stream to monitor progress — See what the agent is doing:

goflow run --workflow my.yaml --verbose  # See tool calls
goflow run --workflow my.yaml --stream   # See LLM output

Simplify the prompt — Complex prompts may cause the agent to spin
Split into smaller steps — Break down the task for better visibility

"agent file not found: X"¶

Problem: Can't find the referenced .agent.md file.

Error: agent file not found: ./agents/reviewer.agent.md

Solutions:

Check the path — Paths are relative to the workflow file:

workflows/
  my-workflow.yaml
agents/
  reviewer.agent.md

# In my-workflow.yaml:
file: "../agents/reviewer.agent.md"

Check file extension — Must be .agent.md

Use absolute path — For debugging:

file: "/full/path/to/reviewer.agent.md"

"template error: step X not found"¶

Problem: Referencing a step that doesn't exist.

Error: template error: step 'analize' not found (did you mean 'analyze'?)

Solution: Fix the typo in your template:

# ✗ Bad
prompt: "Use {{steps.analize.output}}"

# ✓ Good
prompt: "Use {{steps.analyze.output}}"

"condition references unknown step"¶

Problem: A condition references a non-existent step.

Error: condition references unknown step: 'check'

Solution: Verify the step ID in your condition:

- id: review
  condition:
    step: initial-check  # Must match an actual step ID
    contains: "APPROVE"

Mock Mode Issues¶

Mock mode shows "mock output" but real mode fails¶

Problem: Workflow works in mock mode but fails with real AI calls.

Possible causes:

Copilot CLI not installed

which copilot
# If empty, install Copilot CLI
# The SDK executor manages the CLI automatically, but the binary must be on PATH

Not authenticated
```
copilot auth status
```
Model not available — Check if the specified model is accessible to your account
Try the CLI fallback — If the SDK executor has issues, run with --cli to use the legacy subprocess executor:
```
goflow run --workflow my-workflow.yaml --cli
```

Agent Issues¶

Agent tools not working¶

Problem: Agent can't use expected tools.

Solutions:

Check tool is listed:

agents:
  reviewer:
    inline:
      tools:
        - grep
        - read_file  # Must be listed

Use correct tool names:

# ✓ Correct
tools: [grep, semantic_search, read_file]

# ✗ Wrong
tools: [search, open_file, terminal]

Agent seems to ignore instructions¶

Problem: Agent doesn't follow the system prompt.

Solutions:

Make instructions clearer:

prompt: |
  IMPORTANT: You MUST do X.
  NEVER do Y.
  Always format output as [FORMAT].

Check prompt isn't too long — Very long prompts may have key instructions ignored

Use stronger directives:

prompt: |
  CRITICAL RULES (follow exactly):
  1. Always cite line numbers
  2. Use severity levels: CRITICAL, HIGH, MEDIUM, LOW
  3. Never use the phrase "I think"

Audit Trail Issues¶

Audit directory not created¶

Problem: No .workflow-runs/ directory appears.

Solutions:

Check write permissions:
```
touch .workflow-runs/test
```

Specify explicit path:

config:
  audit_dir: "/tmp/goflow-runs"

Old runs not cleaned up¶

Problem: Audit directory grows indefinitely.

Solution: Configure retention:

config:
  audit_retention: 10  # Keep only last 10 runs

Template Issues¶

Template not replaced¶

Problem: {{inputs.X}} or {{steps.Y.output}} appears literally in output.

Solutions:

Check syntax — No spaces inside braces:

# ✓ Good
{{inputs.files}}

# ✗ Bad
{{ inputs.files }}

Check field name exists:

inputs:
  files:  # This name
    ...

prompt: "{{inputs.files}}"  # Must match

Output truncated unexpectedly¶

Problem: Step output is shorter than expected.

Solution: Adjust truncation settings:

config:
  truncate:
    strategy: "lines"
    limit: 500  # Increase limit

Or disable for specific output:

output:
  steps: [summary]
  truncate:
    strategy: "chars"
    limit: 999999  # Effectively unlimited

Getting More Help¶

1. Enable Verbose Mode¶

goflow run --workflow example.yaml --verbose

Shows step-by-step progress and timing.

2. Check the Audit Trail¶

Every run saves the exact prompts and outputs:

cat .workflow-runs/*/steps/*/prompt.md   # What was sent
cat .workflow-runs/*/steps/*/output.md   # What was received

3. Run Single Steps¶

Isolate problem steps:

goflow run --workflow example.yaml --step problematic-step --mock

4. Validate First¶

Check YAML structure before running:

goflow validate --workflow example.yaml

Still Stuck?¶

Search existing issues on GitHub
Create a minimal reproducible example
Open an issue with:
Your workflow file (sanitized)
The error message
goflow version output
Steps to reproduce