Troubleshooting

Common issues and how to fix them. Start with pilot doctor — it catches most configuration problems.


pilot doctor

Installation Issues

”pilot: command not found”

The binary isn’t in your PATH.


# Check if it's installed
ls ~/.local/bin/pilot
 
# Add to PATH (add to your shell rc file)
export PATH="$HOME/.local/bin:$PATH"

If installed via Homebrew, it should be in PATH automatically. Try opening a new terminal.

”permission denied” when running pilot


chmod +x ~/.local/bin/pilot

On macOS, you may also need to remove the quarantine attribute:


xattr -d com.apple.quarantine ~/.local/bin/pilot

Claude Code Issues

”claude: command not found”

Claude Code isn’t installed or isn’t in PATH.


npm install -g @anthropic-ai/claude-code

Verify: claude --version

Claude Code authentication errors

If using a Claude subscription:


claude login

If using an API key:


export ANTHROPIC_API_KEY="your-key"

Pilot delegates all AI execution to Claude Code. If claude -p "hello" works in your terminal, Pilot will work too.

Issue Detection

Pilot doesn’t pick up my issue

Check the label — must be exactly pilot (case-sensitive, no spaces)

Check polling is enabled — verify config:


adapters:
  github:  # or gitlab
    polling:
      enabled: true
      interval: 30s

Check the token — GITHUB_TOKEN must have repo scope
Check the repo — adapters.github.repo must match owner/repo exactly
Check the project path — project_path must point to a valid local clone

Issues are picked up but nothing happens

Check pilot start output for errors
The issue may have been processed before — Pilot adds pilot-in-progress label
Stale pilot-in-progress labels block re-processing. Remove them manually or wait for stale cleanup (default: 1 hour)

PR Issues

PR creation fails

GitHub: Token needs repo scope. Check with gh auth status
GitLab: Token needs api, read_repository, write_repository scopes
Branch conflicts: If the branch already exists, Pilot may fail to push. Delete stale branches: git push origin --delete pilot/issue-name

PR quality is low

Initialize context intelligence — run claude /nav-init inside Claude Code in your project
Add CLAUDE.md — describe your code standards, patterns, and conventions
Write better tickets — treat them like briefings for a junior developer. Include context, requirements, and expected behavior
Configure quality gates — auto-detected or in config. Failed gates get retried with error feedback

Upgrade Issues

”Homebrew installation detected”

pilot upgrade is blocked for Homebrew installs. Use:


brew upgrade pilot

Or switch to self-managed installation:


brew uninstall pilot
curl -fsSL https://raw.githubusercontent.com/alekspetrov/pilot/main/install.sh | bash

Upgrade failed / binary corrupted


pilot upgrade rollback

This restores the backup created during the upgrade.

Performance

Token costs seem high

Context intelligence reduces token usage by ~92% — make sure .agent/ is initialized in your project

Model routing — enable to route trivial tasks to Haiku instead of Opus:


executor:
  model_routing:
    enabled: true
    trivial: "claude-haiku"

Budget limits — set daily/monthly caps to prevent runaway spend:
```
budget:
  enabled: true
  daily_limit: 50.00
```

Tasks take too long

Check executor.timeout.default — default is 30 minutes
Complex tasks may benefit from epic decomposition:
```
executor:
  decompose:
    enabled: true
```
Use the dashboard (pilot start --dashboard) to monitor progress in real-time

Worktree Isolation

Orphaned worktrees after crash

If Pilot crashes mid-execution, worktrees may be left behind in /tmp/. On next startup, Pilot automatically scans for and removes orphaned worktrees.

Manual cleanup (if needed):


# List orphaned worktrees
ls /tmp/pilot-worktree-*
 
# Remove all orphaned worktrees
rm -rf /tmp/pilot-worktree-*
 
# Clean git references
git worktree prune

“failed to create worktree” error

The branch may already exist from a previous run:


# Check existing worktrees
git worktree list
 
# Remove stale worktree reference
git worktree prune
 
# If branch exists, delete it
git branch -D pilot/GH-<issue>

Context intelligence not working in worktree

Worktrees only contain tracked files from HEAD. If your .agent/ directory has untracked content:

Check if .agent/ is gitignored: Untracked .agent/ content is copied automatically
Verify copy succeeded: ls -la /tmp/pilot-worktree-*/.agent/
Check permissions: Files should maintain original permissions

If context intelligence still doesn’t work, verify the source repo has a valid .agent/ directory:


ls -la .agent/
ls -la .agent/tasks/

Worktree execution hangs

Check for network issues or locked resources:


# Verify remote access from worktree
git -C /tmp/pilot-worktree-* ls-remote origin
 
# Check for process holding locks
lsof +D /tmp/pilot-worktree-*

Disk space issues

Worktrees are created in /tmp/ and cleaned up automatically. If disk is full:


# Check tmp usage
du -sh /tmp/pilot-worktree-*
 
# Remove all worktrees (safe if no tasks running)
rm -rf /tmp/pilot-worktree-*
 
# Clear system temp files
# macOS: let system handle /tmp cleanup
# Linux: check if /tmp is on tmpfs

Dashboard

Dashboard doesn’t show updates

Make sure you’re running with --dashboard flag
Refresh interval is configurable: dashboard.refresh_interval: 1000 (ms)
SQLite WAL mode should handle concurrent access — if issues persist, check file permissions on ~/.pilot/data/

Dashboard shows “Update available” but won’t upgrade

Press u to trigger the upgrade
If tasks are running, Pilot waits up to 2 minutes for them to complete
Homebrew installs can’t self-upgrade — see Upgrade Issues above

GitHub API Rate Limits

Pilot hits GitHub rate limit (429 errors)

The scheduler handles this automatically, but you can reduce API usage:

Use webhooks instead of polling — Zero quota for issue detection:
```
pilot start --github --tunnel
```

Increase poll interval — If webhooks aren’t an option:


orchestrator:
  execution:
    poll_interval: 60s  # Default is 30s

Check rate limit status:
```
gh api rate_limit
```

The scheduler tracks quota via response headers and automatically waits for reset (with a 5-minute safety buffer).

Database Issues

”Database is locked” error

Fixed in v1.5.2. If you see SQLITE_BUSY or “Database locked, retrying” in logs:

Upgrade to v1.5.2+:
```
pilot upgrade
```
Check for multiple instances — Only one Pilot process should access the database:
```
pgrep -f "pilot start"
```

Verify WAL mode — Should be enabled automatically:


sqlite3 ~/.pilot/data/pilot.db "PRAGMA journal_mode"
# Should return: wal

Dashboard freezes or hangs

Often caused by the same SQLite contention. Check logs for “Database locked, retrying” messages:


grep -i "database.*locked\|sqlite.*busy" ~/.pilot/logs/pilot.log

If present, upgrade to v1.5.2+ which includes:

WAL mode for concurrent access
Connection serialization
Automatic retry with backoff

Getting Help

If none of the above resolves your issue:

Check existing issues: github.com/alekspetrov/pilot/issues
Run with debug logging: set logging.level: "debug" in config
Open a new issue with pilot doctor output and relevant logs