Skip to main content
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' does not output 'msg'",
    "node_id": "process",
    "available_fields": ["result", "result.messages", "result.messages[0].text"],
    "fixable": true
  }]
}
Your agent sees that msg doesn’t exist, but result.messages 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.

​
Trace files

pflow automatically saves detailed execution traces:
  • Location: ~/.pflow/debug/workflow-trace-*.json
  • When: Every workflow run (success or failure)
  • Content: Per-node timing, inputs, outputs, errors
Your agent reads these when it needs more context to diagnose a failure. You don’t need to inspect them yourself - they’re designed for your agent to parse.
Trace file inspection requires local filesystem access. This works with Claude Code, Cursor, and similar tools that can read files on your machine. Desktop apps like Claude Desktop or ChatGPT Desktop don’t have filesystem access by default - you’d need to configure an MCP server that provides file reading capabilities.
Traces are saved automatically. Use --no-trace if you want to disable this.

​
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 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.

​
Disk cleanup

Trace files accumulate over time. pflow doesn’t auto-delete them. If disk space becomes an issue: 
# Remove old traces (check contents first if needed)
rm ~/.pflow/debug/workflow-trace-*.json

​
Summary

SituationWho handles it
Workflow fails with fixable errorYour agent (self-corrects)
Agent needs more contextYour agent (reads trace files)
API key not configuredYou (agent tells you the command)
MCP server not connectedYou (agent guides you)
Disk space from tracesYou (manual cleanup)
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.