Troubleshooting¶

Common issues and solutions.

Installation Issues¶

"Command not found: claudesprint"¶

The package isn't in your PATH.

Solution:

# Check if installed
pip show claudesprint

# If installed, find location
python -c "import claudesprint; print(claudesprint.__file__)"

# Reinstall with pipx for better PATH handling
pipx install claudesprint

"Command not found: claude"¶

Claude Code CLI is not installed.

Solution: 1. Install from official guide 2. Verify: claude --version 3. Authenticate: claude login

"Claude CLI not authenticated"¶

You need to log in.

Solution:

claude login

Runtime Issues¶

"current_issue.json validation failed"¶

The issue state file is corrupted or incomplete.

Solution:

# See what's wrong
claudesprint validate

# Reset the current issue
claudesprint reset

Stuck in a loop¶

The workflow keeps retrying the same step.

Diagnosis:

# Check current state
claudesprint status

# View failure details
cat .claudesprint/project/current_issue.json | jq '.current_failures'

Solutions: 1. Check if tests are actually passing locally 2. Review the spec for ambiguous requirements 3. Reset and try again:

claudesprint reset
claudesprint run -n 3

Max retry limit reached¶

Too many failed attempts on one issue.

Solution:

# Check what's failing
claudesprint status

# Increase limit temporarily
CLAUDESPRINT_MAX_RETRY=10 claudesprint run

# Or reset and fix manually
claudesprint reset

Tests pass locally but fail in ClaudeSprint¶

Environment differences between your shell and Claude's session.

Common causes: - Missing environment variables - Different working directory - Node modules not installed

Solution: Ensure your test command works from project root:

cd /path/to/project
npm test  # Should work from here

Update hooks.json if needed:

{
  "test": {
    "command": "cd /absolute/path && npm test",
    "timeout": 300
  }
}

Browser Automation Issues¶

"agent-browser not found"¶

Browser automation tool not installed.

Solution:

npm install -g agent-browser
agent-browser install  # Install browser deps

Browser validation failing¶

Browser tests can't connect or interact.

Solutions: 1. Ensure dev server is running:

npm run dev  # In another terminal

Check project config:

{
  "dev_server": {
    "url": "http://localhost:3000",
    "health_check": "/health"
  }
}

Reinstall browser dependencies:

agent-browser install --with-deps  # Linux
agent-browser install              # macOS

State Issues¶

"Sprint file not found"¶

No sprint initialized for this project.

Solution:

# Initialize from spec
claudesprint init --spec SPEC_01.md

# Or check if spec exists
ls .claudesprint/specs/

"Session lock held by another process"¶

Another ClaudeSprint instance is running.

Solution:

# Check for running processes
ps aux | grep claudesprint

# Remove stale lock (if no process running)
rm .claudesprint/state/session.lock

Corrupted sprint.json¶

Sprint file is invalid JSON.

Solution:

# Validate
python -m json.tool .claudesprint/sprints/SPEC_01/sprint.json

# Re-initialize from spec
claudesprint init --spec SPEC_01.md

Performance Issues¶

Workflow running slowly¶

Each step takes too long.

Diagnosis: - Check iteration count with claudesprint status - Watch dashboard for bottlenecks

Solutions: 1. Use Sonnet for more steps:

CLAUDESPRINT_MODEL_OVERRIDE=sonnet claudesprint run

Simplify test suite (faster feedback)
Break large issues into smaller ones

High API costs¶

Using too many tokens.

Solutions: 1. Limit iterations:

claudesprint run -n 5

Use cheaper models:

CLAUDESPRINT_MODEL_OVERRIDE=sonnet claudesprint run

Write more specific specs (fewer retries)

Getting Help¶

Check environment¶

claudesprint doctor

View logs¶

# Current issue log
cat .claudesprint/project/current_issue.log

# Run with verbose output
claudesprint run -v

Report issues¶

Include: - Output of claudesprint doctor - Output of claudesprint status - Contents of current_issue.json (sanitized) - Steps to reproduce

Report at: github.com/arc-co/claudesprint/issues