# How to Troubleshoot PrimeAgent Errors: A Layer-by-Layer Diagnostic Guide

> Troubleshoot PrimeAgent errors with our layer-by-layer guide. Use prime-agent doctor, status, and logs to fix daemon, worker, kernel, harness, or RLM issues. Resolve problems fast.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-20

---

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

| Layer | Responsibility | Key Source File |
|-------|----------------|---------------|
| **Daemon** | Background service that spawns workers, tracks sessions, and stores persistent state | [[`packages/coding-agent/docs/daemon.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/daemon.md)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/daemon.md) |
| **Worker** | Short-lived process that runs a single sub-agent or tool invocation | [[`packages/coding-agent/src/worker.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/worker.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/worker.ts) |
| **Kernel** | IPython runtime that executes model-generated Python code | [[`packages/coding-agent/src/kernel.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/kernel.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/kernel.ts) |
| **Harness** | Stores supplemental prompts, memories, skill definitions, and sub-agent specifications | [[`packages/coding-agent/src/harness.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts) |
| **RLM** | Recursive Language Model layer that maps tool calls to sub-agents | [[`packages/coding-agent/src/rlm.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/rlm.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/rlm.ts) |
| **CLI / TUI** | User-facing front-end that parses commands like `/login`, `/refine`, `/heartbeat` | [[`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts) |

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)](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.

```bash

# 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:

```bash

# 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:

```bash
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:

```bash
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:

```bash
prime-agent --json <<EOF
{
  "command": "echo Hello world",
  "type": "shell"
}
EOF

```

Pipe through `jq` to isolate structural errors in the response:

```bash
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)](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)](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)](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)](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 doctor`** is the unified entry point for troubleshooting PrimeAgent errors—run it first with `--fix` for 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-harness` only 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)](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)](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)](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`.