How to Troubleshoot PrimeAgent Errors: A Layer-by-Layer Diagnostic Guide
Run prime-agent doctor to identify the failing layer, then use prime-agent status and targeted log inspection to resolve daemon, worker, kernel, harness, or RLM errors.
PrimeAgent is an open-source coding agent built on a layered architecture that isolates long-running work and provides rich diagnostics. Understanding how to troubleshoot PrimeAgent errors requires mapping symptoms to the correct architectural layer—daemon, worker, kernel, harness, RLM, or CLI. This guide walks through systematic debugging using built-in commands and source-level insights from the PrimeIntellect-ai/prime-agent repository.
Understanding PrimeAgent's Six-Layer Architecture
PrimeAgent errors propagate through a strict hierarchy. Pinpointing which layer raised the exception determines your fix.
Error flow follows this sequence: CLI parsing → Daemon handling → Worker execution → Logging/Diagnostics. Master this flow to troubleshoot PrimeAgent errors efficiently.
Essential Diagnostic Commands
Verify Daemon Health with prime-agent doctor
The prime-agent doctor command in [packages/coding-agent/src/commands/doctor.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/commands/doctor.ts) is your primary troubleshooting entry point. It queries the daemon for internal health, prints a service summary, and can auto-repair common issues.
# Check if daemon is running and get PID
prime-agent status
# Print concise health report
prime-agent doctor
# Attempt automatic repairs (restart workers, fix sockets, etc.)
prime-agent doctor --fix
Inspect Structured Logs
The daemon writes to $XDG_RUNTIME_DIR/prime-agent (fallback: ~/.prime-agent). Tail these logs for real-time debugging:
# Live daemon log stream
tail -f ~/.prime-agent/logs/daemon.log
# Most recent worker crash (50 lines)
tail -n 50 ~/.prime-agent/logs/worker-$(date +%Y%m%d%H%M%S).log
Reset Corrupted Harness State
When the Continual Harness has corrupt files causing REPL reload failures:
prime-agent doctor --reset-harness
Warning: This deletes supplemental prompts, memories, and skill caches. Use only when prime-agent doctor reports harness corruption.
Mapping Symptoms to Layers
Use this quick-reference table to troubleshoot PrimeAgent errors by symptom:
| Symptom | Likely Layer | Diagnostic Action |
|---|---|---|
| "Failed to connect to daemon" | Daemon startup | Run prime-agent status; verify socket exists at $XDG_RUNTIME_DIR/prime-agent/daemon.sock |
| "Worker exited with code 1" | Worker / Kernel | Run prime-agent doctor --fix; inspect ~/.prime-agent/logs/worker-*.log |
| "Unable to load skill X" | Harness / Skills | Verify .prime-agent/skills/ directory; check prime-agent doctor for missing skill warnings |
| "Tool call failed: …" | RLM / Provider | Re-authenticate with /login; verify ~/.prime-agent/auth.json credentials |
| "JSON parse error" | CLI / RPC | Run prime-agent doctor to dump latest messages; confirm --json flag usage |
Advanced Troubleshooting Techniques
Re-authenticate LLM Providers
Provider authentication failures in the RLM layer often require credential refresh:
prime-agent /login # Select subscription or paste API key
prime-agent doctor --fix # Re-initialize provider connections
Provider configuration persists in ~/.prime-agent/auth.json.
Debug in JSON Mode for Headless Environments
When TUI interactions complicate debugging, use JSON mode for structured output inspection:
prime-agent --json <<EOF
{
"command": "echo Hello world",
"type": "shell"
}
EOF
Pipe through jq to isolate structural errors in the response:
prime-agent --json <<< '{"command":"pwd","type":"shell"}' | jq '.result'
Key Source Files for Deep Debugging
When prime-agent doctor output is insufficient, trace errors directly in the source:
| File | Purpose |
|---|---|
[prime-agent.sh](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) |
Top-level launcher script; environment setup and daemon startup |
[packages/coding-agent/docs/architecture.md](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) |
High-level daemon → worker → kernel → harness stack documentation |
[packages/coding-agent/docs/daemon.md](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/daemon.md) |
Socket protocol and health-check endpoint specifications |
[packages/coding-agent/docs/usage.md](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/usage.md) |
CLI reference including all doctor command options |
Summary
prime-agent doctoris the unified entry point for troubleshooting PrimeAgent errors—run it first with--fixfor automated repairs- Map symptoms to layers using the six-layer architecture: daemon (connectivity), worker/kernel (execution crashes), harness (state corruption), RLM (provider/tool failures), CLI (parsing errors)
- Inspect logs at
~/.prime-agent/logs/for detailed stack traces when automated fixes fail - Reset harness cautiously with
--reset-harnessonly when state corruption is confirmed - Use JSON mode for programmatic debugging in CI/CD or headless environments
Frequently Asked Questions
What does "Worker exited with code 1" mean in PrimeAgent?
This error originates in [packages/coding-agent/src/worker.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/worker.ts) and indicates the short-lived worker process crashed during sub-agent or tool execution. Run prime-agent doctor --fix to restart the worker, then inspect ~/.prime-agent/logs/worker-*.log for the underlying exception—typically a kernel crash or unhandled Python exception in the IPython runtime.
Where does PrimeAgent store its diagnostic logs?
PrimeAgent writes structured logs to $XDG_RUNTIME_DIR/prime-agent if the variable is set, otherwise to ~/.prime-agent/. Key files include daemon.log (background service activity) and timestamped worker-*.log files (individual execution crashes). The prime-agent doctor command reads these files to generate its health report.
How do I fix "Failed to connect to daemon" errors?
This daemon-layer failure means the background service isn't running or its Unix socket is inaccessible. First run prime-agent status to verify daemon state and PID. If stopped, launch with prime-agent directly or check [prime-agent.sh](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) for proper environment initialization. Verify the socket file exists at $XDG_RUNTIME_DIR/prime-agent/daemon.sock and has correct permissions.
When should I use prime-agent doctor --reset-harness?
Use this flag only when prime-agent doctor reports harness corruption or you see "Unable to load skill" errors that persist after restarts. The harness in [packages/coding-agent/src/harness.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts) stores supplemental prompts, memories, and skill caches—resetting wipes this state but does not affect daemon configuration or LLM provider credentials in ~/.prime-agent/auth.json.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →