Reference
Troubleshooting
Common problems, their root causes, and how to fix them. Start here when your workflow behaves unexpectedly.
Agent loops forever
Cause
No exit condition in feedback loop configuration. The agent keeps retrying because it has no maximum retry count or timeout defined.
Fix
Set max retries in your workflow configuration. The recommended default is 3 attempts. After exhausting retries, the loop should escalate to a human rather than continue indefinitely.
Check
Review your quality gate definitions. A gate that can never pass (e.g., checking for a condition the agent cannot satisfy) will cause infinite loops regardless of retry settings.
Tests never pass
Cause
Tests may be flaky or environment-dependent. Tests that rely on external services, specific timing, or hardcoded paths will fail unpredictably in the workflow's isolated worktree environment.
Fix
Ensure deterministic test setup. Check for hardcoded paths, timing dependencies, or reliance on external state. Tests should be self-contained and produce the same result every run.
Context window exceeded
Cause
Too much context loaded into a single agent. Reading entire files, including full dependency trees, or loading all project documentation at once will exceed the model's context window.
Fix
Use subagents to split work across smaller, focused tasks. Reduce file read scope by targeting specific functions or sections. Use targeted grep instead of full file reads. Structure prompt templates to request only the context needed for each phase.
Permission errors
Cause
Agent trying to use tools outside its permission boundary. For example, a Plan phase agent attempting to write files, or a Build agent trying to push to the remote repository.
Fix
Check phase-specific tool permissions in your workflow configuration. Each phase should have explicit allow/deny lists for tools. The Plan phase should be read-only. The Build phase should have file write but no git push. The Deploy phase handles repository operations.
Plan doesn't match implementation
Cause
Build agent drifting from the spec. Without constraints, agents may add features not in the plan, restructure code beyond scope, or take a different architectural approach than specified.
Fix
Enable the review loop to catch drift early. Add scope guards to your build prompt template that explicitly instruct the agent to implement only what the plan specifies. Use the diff-to-plan ratio agentic KPI to track and measure drift over time.