tomevault-io Debugging Orchestration Workflows
I help diagnose and fix workflow execution issues using systematic debugging techniques.
When I Activate
I activate when you:
- Experience workflow failures
- Get syntax errors
- Have agent execution issues
- Variables not working as expected
- Ask "why isn't this working?"
Common Issues
Syntax Errors
Problem: Workflow won't parse
Symptoms:
- "Unexpected token" errors
- "Invalid syntax" messages
- Workflow won't start
Solutions:
- Check operator syntax:
->,||,~>(not=>or&&) - Verify bracket matching:
[...] - Check quote matching:
"instruction" - Validate agent names (no typos)
Agent Not Found
Problem: Agent reference doesn't resolve
Symptoms:
- "Agent 'X' not found"
- Execution stops at agent invocation
Solutions:
- Check spelling of agent name
- Verify temp agent file exists:
temp-agents/agent-name.md - Check defined agent in registry:
agents/registry.json - Ensure built-in agent name is correct
Variable Issues
Problem: Variables not passing correctly
Symptoms:
{variable}shows as literal text- "Variable not found" errors
- Empty variable values
Solutions:
- Verify capture syntax:
agent:"task":variable_name - Check interpolation:
"Use {variable_name}" - Ensure variable set before use
- Check variable name spelling
Parallel Execution Failures
Problem: Parallel tasks failing or hanging
Symptoms:
- Only some parallel tasks complete
- Workflow hangs at parallel section
- Inconsistent results
Solutions:
- Ensure tasks are independent (no shared state)
- Check syntax:
[task1 || task2 || task3] - Verify each task can run standalone
- Check for race conditions
Checkpoint Issues
Problem: Checkpoints not triggering
Symptoms:
- Checkpoints skipped
- No user prompt shown
- Workflow continues without pause
Solutions:
- Check checkpoint syntax:
@checkpoint-name - Verify not in auto-mode
- Ensure checkpoint is reachable in flow
Debugging Process
1. Reproduce
Run workflow with minimal changes to reproduce issue.
2. Isolate
Simplify workflow to find problematic section:
# If this fails:
step1 -> step2 -> step3 -> step4
# Try:
step1 -> step2 # Works?
step3 -> step4 # Works?
3. Inspect
Check execution logs for error details.
4. Fix
Apply targeted fix based on findings.
5. Verify
Run full workflow to ensure fix works.
Error Messages Guide
| Error | Meaning | Fix |
|---|---|---|
| "Unexpected token" | Syntax error | Check syntax around error location |
| "Agent not found" | Missing agent | Verify agent exists and spelling |
| "Variable not found" | Variable undefined | Check variable was captured |
| "Condition failed" | Condition not met | Check condition logic |
| "Execution timeout" | Task took too long | Add timeout handling or simplify task |
Best Practices
✅ DO:
- Start with simple workflow, add complexity gradually
- Test each section independently
- Use meaningful variable names
- Add error handling paths
- Capture outputs for debugging
❌ DON'T:
- Create overly complex workflows initially
- Skip testing individual steps
- Use cryptic variable names
- Ignore error messages
- Remove error handling
Diagnostic Commands
# Check temp agents exist
ls temp-agents/
# Verify agent registry
cat agents/registry.json
# Check workflow syntax file
cat examples/workflow-name.flow
Related Skills
- creating-workflows: Create well-structured workflows
- executing-workflows: Execute with better error visibility
- managing-agents: Debug agent-related issues
Workflow not working? Show me the error and I'll help debug!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.