# Prime Agent Troubleshooting: Common Issues and Fixes for PrimeIntellect-ai/prime-agent

> Troubleshoot common Prime Agent issues like daemon crashes, auth failures, and timeouts. Learn quick fixes and use doctor commands for PrimeIntellect-ai/prime-agent.

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

---

**The most common Prime Agent problems involve daemon crashes, authentication failures, session persistence errors, and worker/kernel timeouts—all diagnosable with built-in `doctor` commands and environment variable fixes.**

Prime Agent is a multi-process, daemon-backed coding assistant built around a **Recursive Language Model (RLM)** and persistent IPython kernel. Because it combines CLI/TUI front-ends, supervisor daemons, worker processes, and pluggable model providers, failures can surface across multiple layers. This guide covers the eight most frequent Prime Agent troubleshooting scenarios, their root causes in the source code, and actionable fixes.

## Installation Failures and Fixes

The `curl … | sh` installer or `npm ci` builds occasionally fail due to environment mismatches.

**Root causes:**
- Node.js version below 22.8.0
- Outdated npm workspace identifiers
- Missing `/usr/local/bin` in `$PATH` on macOS/Linux

**Solutions:**

```bash

# Verify Node version (required: ≥ 22.8.0)

node --version

# Clean install from source

git clone https://github.com/PrimeIntellect-ai/prime-agent.git
cd prime-agent
npm ci

# Ensure binary is reachable

export PATH="/usr/local/bin:$PATH"
prime-agent --version

```

If the `prime-agent` binary remains missing, the install script likely failed to link the CLI. Re-run with `curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh` and check for network errors.

## Authentication and API Key Problems

Prime Agent stores provider credentials in `~/.prime/agent/auth.json`. Authentication failures typically produce "/login returns provider not found" or rejected model calls.

**Resolution steps:**

1. **Run `/login`** inside an active Prime Agent session to select a provider interactively.

2. **Export the correct environment variable** for your provider:

   ```bash
   export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
   export OPENAI_API_KEY=sk-xxxxxxxxxxxx
   ```

3. **Clear stale credentials** if keys were rotated:

   ```bash
   rm ~/.prime/agent/auth.json
   ```

The authentication flow does not validate keys until the first model call, so a silent failure may only surface during inference.

## Daemon and Supervisor Crashes

The `prime-agent status` command reporting "daemon not running" or `Error: Sessions directory not found` indicates supervisor failure. This logic resides in `packages/coding-agent/src/daemon/` with validation in [`scripts/tool-stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/tool-stats.ts).

**Diagnostic commands:**

```bash

# Check daemon health

prime-agent status

# Auto-repair directories and PID files

prime-agent doctor --fix

# View recent crash logs

prime-agent doctor --log

# Nuclear option: kill all processes and restart

pkill -f prime-agent
prime-agent

```

The daemon creates `~/.prime/agent/sessions/` for persistence. If this directory is missing or permissions are restricted, [`scripts/tool-stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/tool-stats.ts) throws `throw new Error('Sessions directory not found…')` as referenced in the source.

## Worker, Kernel, and LSP Connection Failures

Truncated model output, `Error: peer unavailable`, or `Timed out waiting for snapshot` indicate worker process death or IPython kernel disconnection.

**Required environment:**
- Python ≥ 3.10 with `ipykernel` installed
- Valid `PRIME_AGENT_KERNEL_PYTHON` pointing to interpreter

```bash

# Force interpreter selection

export PRIME_AGENT_KERNEL_PYTHON=$(which python3)

# Verify kernel availability

python3 -m ipykernel --version

# Re-attach to surviving session after crash

prime-agent agents                    # list session IDs

prime-agent attach <session-id>

```

Kernel sockets can break during long sessions. If `prime-agent attach` fails with peer errors, the kernel process died—start a fresh session and migrate context manually.

## Session Persistence and Snapshot Errors

Sessions disappear or fail to load when JSONL files in `~/.prime/agent/sessions/` are corrupted or missing.

**Verification steps:**

```bash

# List session storage

ls ~/.prime/agent/sessions/

# View live sessions (may differ from disk if daemon crashed)

prime-agent agents

# Force cleanup of zombie workers

prime-agent shutdown --force

```

Corrupted session files cannot be repaired—Prime Agent does not implement automatic backup snapshots. For critical work, export sessions periodically or rely on external version control.

## Model Provider Errors and Rate Limits

"Network failed", "offline", and "provider returned an error" map to three distinct causes:

| Symptom | Check | Command |
|---------|-------|---------|
| Network layer | API connectivity | `curl https://api.anthropic.com/v1/models` |
| Rate limiting | HTTP 429 responses | Switch via `/model` or `Ctrl+L` |
| Subscription status | Account dashboard | Verify at provider portal |

The `/model` TUI command (`Ctrl+L`) hot-swaps providers without restart, implemented in [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) error propagation paths.

## Tool and Skill Execution Failures

`Error: expected tool metadata`, `disk offline`, or "cannot edit file" indicate plugin or permission problems.

**Fixes:**

- **Install missing skill**: `npm i @prime/skill-example`
- **Grant workspace permissions**: Run Prime Agent from a writeable directory, not system paths
- **Check sandbox restrictions**: Some skills require explicit file-system access grants

Skill plugins load dynamically; missing metadata errors occur when `npm` packages lack the required `prime-skill` manifest fields in [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json).

## TUI and CLI Interface Glitches

Keyboard shortcuts (`Ctrl+O`, `Ctrl+P`, mouse events) fail in terminals lacking proper escape sequence support.

**Compatible terminals:** iTerm2, Kitty, GNOME Terminal, Windows Terminal

**tmux-specific fix:**

```bash

# Fixed-size session prevents resize glitches

tmux new-session -d -s prime -x 80 -y 24
prime-agent

```

The TUI core in [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) throws `throw new Error(errorMsg)` for rendering failures—often masking as hangs when the terminal does not respond to cursor position queries.

## Performance Degradation and Timeouts

Long-running sessions become sluggish due to scheduler overload, high autonomous token budgets, or background job accumulation.

**Mitigation commands:**

```bash

# Reduce autonomous effort

/effort low

# Throttle periodic background work

/heartbeat 30

# Inspect process tree for runaway tasks

/tree

```

Use `/tree` to identify stuck child processes. The RLM scheduler does not auto-kill runaway tool chains without explicit heartbeat timeouts.

## Summary

- **Installation**: Verify Node ≥ 22.8.0 and run `npm ci` from clean checkout
- **Authentication**: Export provider API keys and clear `~/.prime/agent/auth.json` if stale
- **Daemon crashes**: Use `prime-agent doctor --fix` and `pkill -f prime-agent` for recovery
- **Kernel failures**: Set `PRIME_AGENT_KERNEL_PYTHON` and re-attach with `prime-agent attach`
- **Session loss**: Check `~/.prime/agent/sessions/` and force shutdown stray workers
- **Provider errors**: Test connectivity with `curl`, switch models via `/model`
- **Skill errors**: Install missing `npm` packages and verify write permissions
- **TUI glitches**: Use modern terminals or fixed-size tmux sessions
- **Performance**: Reduce `/effort`, configure `/heartbeat`, monitor with `/tree`

## Frequently Asked Questions

### Why does Prime Agent say "daemon not running" immediately after installation?

The supervisor daemon failed to start, usually due to missing `~/.prime/agent/sessions/` directory or stale PID files from a previous crash. Run `prime-agent doctor --fix` to auto-repair directories, or manually run `pkill -f prime-agent` followed by `prime-agent` to clear orphaned processes.

### Where does Prime Agent store API keys and session data?

Credentials live in `~/.prime/agent/auth.json`. Session persistence uses JSONL files in `~/.prime/agent/sessions/`. Both paths are validated at startup; [`scripts/tool-stats.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/tool-stats.ts) throws explicit errors if directories are absent according to the source implementation.

### How do I recover a session after the IPython kernel crashes?

First attempt `prime-agent attach <session-id>` after listing IDs with `prime-agent agents`. If this fails with "peer unavailable," the kernel process died and cannot be recovered—start a new session. Set `PRIME_AGENT_KERNEL_PYTHON` explicitly to prevent interpreter mismatches.

### Can I run Prime Agent in tmux or over SSH?

Yes, but terminal capabilities vary. Use modern terminals (iTerm2, Kitty, GNOME Terminal) supporting mouse and escape sequences. For tmux, create sessions with fixed dimensions: `tmux new-session -d -s prime -x 80 -y 24`. SSH works provided the remote host meets Python ≥ 3.10 and Node ≥ 22.8.0 requirements.