How debugging works

When workflows fail, pflow gives your agent structured error data — available fields, types, and fix suggestions. Since agents build and fix workflows, error messages are the primary interface. They say what’s wrong, what’s available instead, and how to fix it. Your role in debugging is minimal. Most of the time, you don’t need to do anything.

Your agent handles most debugging

When a workflow fails, your agent receives detailed information about what went wrong:

What failed - Which node, what error category
What’s available - The fields that DO exist (not just what’s missing)
Suggestions - “Did you mean?” recommendations
Execution state - Which nodes succeeded before the failure

Your agent uses this to self-correct. When building or fixing workflows, it reads pflow’s built-in instructions — how to interpret errors, inspect trace files, and resolve common issues. You don’t need to teach your agent how to debug. The guidance is built in.

What your agent sees

When a workflow fails, errors include the data needed for self-correction:

{
  "errors": [{
    "message": "Node 'fetch' (type: shell) does not output 'msg'.",
    "suggestions": ["Try ${fetch.stdout}"],
    "node_id": "fetch",
    "context": {
      "category": "template_error",
      "available_fields": ["${fetch.stdout} (str)", "${fetch.stderr} (str)", "${fetch.exit_code} (int)"]
    }
  }]
}

Your agent sees that msg doesn’t exist, but stdout does. It fixes the template and retries. No human intervention needed. These errors are specific because the error space is finite — pflow knows every node type and every declared output. When agents compose known building blocks instead of writing arbitrary code, errors say “node X doesn’t output Y, did you mean Z?” instead of handing you a stack trace.

Execution reports

The --report flag generates a structured execution report — a directory of readable markdown files, one per node:

# Report to default location (~/.pflow/reports/{name}/)
pflow my-workflow --report

# Report to a specific directory
pflow my-workflow --report-dir ./report/

The report includes:

summary.md — pipeline table with per-node cost, errors with fix suggestions, anomaly warnings for suspicious empty outputs
Per-node files — rendered prompts (what the LLM actually received), full responses, model/token/cost metadata
Batch items — per-item files showing individual prompts and responses
Sub-workflows — nested directories mirroring the workflow structure

Values under sensitive names (api_key, token, password, Authorization, Cookie, …) show as <REDACTED> in the report, and so does a run’s secret value wherever it appears — in a command, stderr or a response (see secret values). The trace keeps them raw so resume can restore them. Any other secret inside free text, such as a key exported only in your shell, is not detected. Reports are ephemeral — the default location is overwritten each run. The trace files are the run history, kept for the retention window. You can regenerate a report from any run in that window:

# Most recent trace
pflow report

# A specific past run
pflow report ~/.pflow/debug/workflow-trace-3f2a1b9c-my-workflow.0b7e6a52-1c4d-4e8f-9a3b-5d6c7e8f9a0b-20260323-150000-123456.json -o /tmp/old

Report directories are generated snapshots. pflow replaces the whole directory when writing a report so old node pages cannot be mistaken for current-run evidence. Custom report directories must be empty or already contain .pflow-report.json, the marker pflow writes into report output.

Comparing runs with git diff

Write reports to a project-local folder. Stage the report, edit a prompt, re-run — git diff shows exactly what changed:

pflow my-workflow --report-dir ./report/
git add report/

# Edit a prompt, re-run
pflow my-workflow --report-dir ./report/
git diff report/

Each node gets its own file, so you can diff just the node you changed. With stochastic LLM outputs, a full-report diff is noisy — targeted per-node diffs show whether your prompt change had the intended effect.

Trace files

pflow automatically saves detailed execution traces:

Location: ~/.pflow/debug/workflow-trace-{hash}-{name}.{run id}-{start time}.json (a paused run also gets an empty .paused file beside its trace)
When: Every workflow run (success or failure)
Content: Per-node timing, inputs, outputs, template resolutions, errors

Traces are the raw data behind execution reports. Your agent can read these directly when it needs programmatic access, but the --report output is usually more useful for debugging.

Traces are saved automatically. Use --no-trace if you want to disable this (the --report flag overrides --no-trace).

Traces written by an earlier pflow version use an older filename. pflow resume, pflow resume list, pflow report, --only and the Viewer don’t search them. When one of the commands finds nothing, it says how many older traces it skipped (so does the Viewer’s gate panel; its run history and run links don’t). You can still read one with pflow report <path>, and it ages out like any other trace. After upgrading, --only needs one full run first.Answer pending pauses before upgrading, and don’t run an older and a newer pflow against the same ~/.pflow: an older pflow can answer a newer pflow’s pause without the newer one seeing that answer, an older pflow’s settings command drops trace_retention_days from the settings file, and the newer pflow ages out the older one’s traces — pending pauses included — after the window. If you must mix versions and want to keep every trace, set both opt-outs: trace_retention_days: 0 in the settings file (read by every pflow process) and PFLOW_TRACE_RETENTION_DAYS=0 (survives an older version’s settings write, but only for processes that inherit it — an MCP server launched by a desktop app does not see your shell’s exports).

What only you can fix

Some things require human action. Your agent will tell you when these come up:

API key not configured

If pflow’s discovery features aren’t working:

pflow settings set-env OPENAI_API_KEY "sk-..."

pflow auto-detects available providers. You can optionally override the model:

pflow settings llm set-default openai/gpt-5.2

Your agent can’t configure API keys for security reasons, but it will tell you exactly what command to run.

MCP server issues

If your agent reports MCP tools aren’t available:

# Check what servers are configured
pflow mcp list

# Force re-sync if needed
pflow mcp sync --all

See adding MCP servers for setup details.

Trace retention

pflow removes traces older than the retention window — 14 days by default — each time it finishes writing a trace. Read-only commands (pflow report, pflow resume list, pflow ui) never remove anything. Whatever their age, pflow keeps:

a paused run still waiting for an answer
each workflow’s newest successful run (what --only restores from)
each workflow’s newest run, whatever its status (what pflow report shows)
a resumed run’s trace, until the run it resumed is gone
a trace a running workflow is still writing

The first three are kept only while the workflow file still exists — --only and pflow resume need the file. To change the window, set runtime.trace_retention_days in ~/.pflow/settings.json (0 keeps every trace):

{ "runtime": { "trace_retention_days": 30 } }

PFLOW_TRACE_RETENTION_DAYS overrides it for one process (in your shell, or stored with pflow settings set-env) and is never saved to runtime. Spell the opt-out exactly. If pflow can’t trust the setting — the settings file fails to load, a retention-looking key is misspelled or in the wrong section, a PFLOW_ variable looks like a misspelling of PFLOW_TRACE_RETENTION_DAYS, or the value isn’t a whole number of days — it removes nothing and prints a warning saying why. pflow settings show ends with the retention window in effect. Don’t delete traces by hand: removing a trace breaks --only, pflow resume, the answer to a pending pause and pflow report for that run.

Summary

Situation	Who handles it
Workflow fails with fixable error	Your agent (self-corrects)
Agent needs more context	Your agent (reads trace files)
API key not configured	You (agent tells you the command)
MCP server not connected	You (agent guides you)
Disk space from traces	pflow (retention; `trace_retention_days`)

pflow is built for self-correction. Your agent has the tools and knowledge to debug most issues — you only step in for setup tasks that require human access.

Getting started

Guides

AI tool integration

How debugging works

Your agent handles most debugging

What your agent sees

Execution reports

Comparing runs with git diff

Trace files

What only you can fix

API key not configured

MCP server issues

Trace retention

Summary

​Your agent handles most debugging

​What your agent sees

​Execution reports

​Comparing runs with git diff

​Trace files

​What only you can fix

​API key not configured

​MCP server issues

​Trace retention

​Summary

Your agent handles most debugging

What your agent sees

Execution reports

Comparing runs with git diff

Trace files

What only you can fix

API key not configured

MCP server issues

Trace retention

Summary