Common Issues

This page covers frequently encountered issues and their solutions. For each problem, we provide symptoms, causes, and step-by-step solutions.

Agent Issues

Agent Not Found

Symptoms:

Error: cursor: command not found
Error: spawn cursor ENOENT

Cause: The AI agent CLI is not installed or not in your PATH.

Solutions:

  1. Verify agent installation:
# For Cursor CLI
which cursor

# For Claude Code
which claude

# For Codex
which codex

If the command returns nothing, the agent isn’t in your PATH.

  1. Install the agent:
  1. Add agent to PATH:

If installed but not in PATH, add the installation directory:

# For bash
echo 'export PATH="/path/to/agent:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="/path/to/agent:$PATH"' >> ~/.zshrc
source ~/.zshrc
  1. Verify Ralph can find the agent:
ralph config

Check that the agent setting matches your installed agent.

Agent Keeps Timing Out

Symptoms:

  • Iterations consistently hit the 30-minute timeout
  • Ralph retries but times out again
  • Tasks are never completed

Causes:

  • Tasks are too complex for the timeout window
  • Agent is working on large files or complex operations
  • System is slow or under heavy load

Solutions:

  1. Increase the timeout:

Edit ~/.ralph/config.json:

{
  "agentTimeoutMs": 3600000
}

Common timeout values:

  • 1800000 (30 min) — Default, good for most tasks
  • 3600000 (1 hour) — Complex refactors
  • 5400000 (90 min) — Large migrations
  • 7200000 (2 hours) — Extremely complex tasks
  1. Break tasks into smaller pieces:
# View current task
ralph task current

# If too large, break it down
ralph task remove 3
ralph task add --title "Smaller subtask 1"
ralph task add --title "Smaller subtask 2"
  1. Check system resources:
# CPU usage
top

# Memory usage
free -h

# Disk I/O
iostat

If system is overloaded, close other applications or increase resources.

  1. Try a different agent:

Some agents work better for certain tasks:

{
  "agent": "claude"
}

Agent Appears Stuck

Symptoms:

  • Agent runs but produces no output for 5+ minutes
  • Terminal shows no activity
  • Ralph eventually triggers stuck detection

Causes:

  • Agent is waiting for user input (shouldn’t happen but can)
  • Agent is processing large files
  • Network issues (agent can’t reach API)
  • Agent crashed but process didn’t exit

Solutions:

  1. Reduce stuck threshold for faster detection:
{
  "stuckThresholdMs": 180000
}
  1. Check agent process:
# Find agent process
ps aux | grep cursor

# If hung, kill it
kill -9 <pid>

# Ralph will detect and retry
  1. Check network connectivity:
# Test internet connection
ping -c 3 google.com

# Check if agent API is reachable
curl -I https://api.cursor.sh
  1. Review logs for clues:
tail -f ~/.ralph/projects/<project>/logs/latest.log

Look for:

  • Network errors
  • API rate limits
  • Authentication issues
  1. Manually complete the task:

If stuck repeatedly on same task:

# Complete it yourself
# ... make the changes ...

# Mark as done
ralph task done 3
ralph progress add "Completed manually due to agent issues"

# Continue with next task
ralph run

Agent Produces Errors

Symptoms:

  • Agent exits with error code
  • Error messages in output
  • Iteration fails immediately

Common Errors and Solutions:

“Permission denied”

# Fix file permissions
chmod +x script.sh

# Fix directory permissions
chmod 755 directory/

“Module not found”

# Install dependencies
npm install
# or
bun install

“Git conflict”

# Resolve conflicts
git status
git diff
# Fix conflicts manually
git add .
git commit

“Database connection failed”

# Check database is running
docker ps

# Verify connection string
cat .env

# Test connection
psql -h localhost -U user -d database

Session Issues

Session Already Running

Symptoms:

Error: A session is already active for this project
Cannot start new session while another is running

Cause: Ralph prevents multiple concurrent sessions on the same project to avoid conflicts.

Solutions:

  1. Check session status:
ralph status
  1. Stop the existing session:
ralph stop

Wait for graceful shutdown, then start new session:

ralph run
  1. Force kill if unresponsive:
# Find Ralph process
ps aux | grep ralph

# Kill it
kill -9 <pid>

# Clean up session state
ralph clear

# Start fresh
ralph run

Can’t Resume Session

Symptoms:

Error: No session to resume
Session file not found or corrupted

Causes:

  • Session was never started
  • Session was cleared
  • Session file was deleted or corrupted
  • Working in wrong directory

Solutions:

  1. Check session state:
ralph status
  1. Verify you’re in the right project:
pwd
ralph projects current
  1. Check if session file exists:
ls -la ~/.ralph/projects/<project>/session.json
  1. If corrupted, start fresh:
ralph clear
ralph run

Session Progress Lost

Symptoms:

  • Progress notes disappeared
  • Task completion status reset
  • Session appears to start from beginning

Causes:

  • Session was cleared with ralph clear
  • Working in wrong directory
  • Project not properly registered
  • Session file was manually deleted

Solutions:

  1. Verify current project:
ralph projects current
  1. Check if you’re in the right directory:
pwd
git remote -v
  1. List all projects:
ralph projects
  1. Check session file:
cat ~/.ralph/projects/<project>/session.json
  1. If data is truly lost, review logs:
ls ~/.ralph/projects/<project>/logs/
cat ~/.ralph/projects/<project>/logs/2024-01-20.log

Logs contain historical progress that can help reconstruct what was done.

Session Won’t Stop

Symptoms:

  • ralph stop hangs
  • Ctrl+C doesn’t work
  • Session continues running

Solutions:

  1. Wait for current iteration to complete:

Ralph tries to stop gracefully, which means waiting for the current iteration to finish.

  1. Force stop with multiple Ctrl+C:
# Press Ctrl+C twice quickly
^C^C
  1. Kill the process:
# Find Ralph process
ps aux | grep ralph

# Kill it
kill -9 <pid>
  1. Clean up afterward:
ralph status  # Verify it stopped
ralph clear   # If needed

Task Issues

No Tasks Found

Symptoms:

Error: No tasks defined in PRD
PRD file is empty or missing

Causes:

  • Project not initialized
  • PRD file was deleted
  • Working in wrong directory

Solutions:

  1. Initialize the project:
ralph init
  1. Verify PRD file exists:
ls -la ~/.ralph/projects/<project>/prd.json
cat ~/.ralph/projects/<project>/prd.json
  1. Manually add tasks:
ralph task add --title "First task"
ralph task add --title "Second task"

Tasks Not Completing

Symptoms:

  • Agent appears to finish work
  • But task status stays pending
  • ralph task list shows no progress

Causes:

  • Agent isn’t calling ralph task done
  • Ralph command not accessible from agent
  • Agent doesn’t have permissions to run commands

Solutions:

  1. Check logs for ralph task done calls:
grep "ralph task done" ~/.ralph/projects/<project>/logs/latest.log
  1. Verify Ralph is in agent’s PATH:
# Test from agent's perspective
which ralph
  1. Manually mark task done:
ralph task done 3
  1. Add explicit instruction:

Create or edit ~/.ralph/projects/<project>/instructions.md:

## Completion Protocol

When you finish a task, you MUST run:
```bash
ralph task done <task-number>
ralph progress add "Description of what was done"

### Wrong Task Being Worked On

**Symptoms:**
- Agent working on task 5 when task 3 is pending
- Tasks completed out of order
- Unexpected task in `ralph task current`

**Causes:**
- Tasks were manually marked done incorrectly
- Task status got out of sync
- Multiple sessions running (shouldn't happen)

**Solutions:**

1. **Check current task:**

```bash
ralph task current
  1. View all task statuses:
ralph task list
  1. Fix incorrect completions:
# Mark incorrectly completed tasks as undone
ralph task undone 5
ralph task undone 4

# Verify order
ralph task list
  1. Manually set correct task:
# Complete tasks up to where you want to be
ralph task done 1
ralph task done 2
# Now task 3 will be current

Task Keeps Failing

Symptoms:

  • Same task fails repeatedly
  • All retries exhausted
  • Ralph moves to next task

Causes:

  • Task is too complex
  • Task description is unclear
  • Agent lacks necessary context
  • Technical blocker (missing dependency, etc.)

Solutions:

  1. Review failure logs:
ralph analyze patterns
  1. Break task into smaller subtasks:
ralph task remove 3
ralph task add --title "Subtask 1: Setup"
ralph task add --title "Subtask 2: Implementation"
ralph task add --title "Subtask 3: Testing"
  1. Add more context via guardrails:
ralph guardrails add "For task 3, use the pattern from src/existing-example.ts"
  1. Complete manually and document:
# Do the work yourself
# ... make changes ...

# Mark done with explanation
ralph task done 3
ralph progress add "Completed manually. Agent struggled with X, used Y approach instead."

GitHub Issues

Not Authenticated

Symptoms:

Error: Not authenticated with GitHub
GitHub operations require authentication

Cause: GitHub credentials not configured or expired.

Solutions:

  1. Check auth status:
ralph auth
  1. Login:
ralph auth login

Follow the OAuth device flow instructions.

  1. If using personal access token:
ralph github set-token ghp_xxxxxxxxxxxxx
  1. Verify authentication:
ralph auth

Should show “Authenticated” status.

Repository Not Found

Symptoms:

Error: Repository not found
Could not detect GitHub repository

Causes:

  • No git remote configured
  • Remote doesn’t point to GitHub
  • Wrong directory

Solutions:

  1. Check git remotes:
git remote -v

Should show a GitHub URL:

origin  git@github.com:user/repo.git (fetch)
origin  git@github.com:user/repo.git (push)
  1. Add GitHub remote if missing:
git remote add origin git@github.com:user/repo.git
  1. Verify you’re in the right directory:
pwd
ls -la .git
  1. Check Ralph can detect it:
ralph github

PR Creation Fails

Symptoms:

Error: Failed to create pull request
API error: 422 Unprocessable Entity

Causes:

  • Branch already exists
  • No changes to commit
  • Insufficient permissions
  • Invalid PR title/body

Solutions:

  1. Check if branch exists:
git branch -a | grep feature-branch
  1. Verify you have changes:
git status
git diff
  1. Re-authenticate with full permissions:
ralph auth logout
ralph auth login

Ensure you grant repo scope.

  1. Try creating PR manually:
gh pr create --title "Test" --body "Test"

If this works, the issue is with Ralph’s integration.

Configuration Issues

Invalid Configuration

Symptoms:

Error: Invalid configuration
Failed to parse config file

Cause: JSON syntax error in config file.

Solutions:

  1. Validate JSON:
cat ~/.ralph/config.json | jq .

If jq reports an error, fix the JSON syntax.

  1. Common JSON errors:
// Bad: Trailing comma
{
  "agent": "cursor",
}

// Good: No trailing comma
{
  "agent": "cursor"
}

// Bad: Single quotes
{
  'agent': 'cursor'
}

// Good: Double quotes
{
  "agent": "cursor"
}
  1. Reset to defaults:
mv ~/.ralph/config.json ~/.ralph/config.json.backup
echo '{"agent": "cursor"}' > ~/.ralph/config.json
  1. Verify configuration:
ralph config

Settings Not Taking Effect

Symptoms:

  • Changed timeout but still timing out at old value
  • Changed agent but still using old one
  • Configuration appears ignored

Causes:

  • Editing wrong config file (global vs project)
  • JSON syntax error (silently ignored)
  • Session started before config change
  • Environment variable override

Solutions:

  1. Stop and restart session:
ralph stop
ralph run

Config is loaded at session start.

  1. Verify which config is active:
ralph config --verbose

Shows source of each setting.

  1. Check for syntax errors:
cat ~/.ralph/config.json | jq .
cat ~/.ralph/projects/<project>/config.json | jq .
  1. Check for environment variable overrides:
env | grep RALPH

Environment variables take precedence over config files.

Memory Issues

Memory Warning

Symptoms:

Warning: Memory usage exceeds 500 MB
Consider reducing maxOutputBufferBytes

Cause: Ralph’s memory usage is high, usually from large agent output.

Solutions:

  1. Reduce output buffer:
{
  "memory": {
    "maxOutputBufferBytes": 2621440
  }
}
  1. Clear session and restart:
ralph stop
ralph clear
ralph run
  1. Check for memory leaks:
# Monitor Ralph's memory usage
ps aux | grep ralph

# If growing continuously, report as bug
  1. Increase system memory or close other applications

Out of Memory

Symptoms:

Error: JavaScript heap out of memory
FATAL ERROR: Reached heap limit

Cause: Ralph ran out of memory, usually on very long sessions.

Solutions:

  1. Increase Node.js memory limit:
export NODE_OPTIONS="--max-old-space-size=4096"
ralph run
  1. Reduce memory thresholds:
{
  "memory": {
    "maxOutputBufferBytes": 1048576,
    "memoryThresholdMb": 512
  }
}
  1. Run shorter sessions:
ralph run 5  # Instead of 20
  1. Clear and restart:
ralph clear
ralph run

Performance Issues

Slow Iterations

Symptoms:

  • Each iteration takes very long
  • Agent appears slow to respond
  • System feels sluggish

Solutions:

  1. Check system resources:
top
free -h
df -h

  1. Close unnecessary applications

  2. Check network speed:

speedtest-cli

Agent APIs require good internet connection.

  1. Try a different agent:

Some agents are faster than others for certain tasks.

High CPU Usage

Symptoms:

  • CPU at 100%
  • System fans running loud
  • Other applications slow

Solutions:

  1. Check what’s using CPU:
top
  1. If agent process is the culprit:

This is normal during active development. Agent is analyzing code and generating responses.

  1. Reduce concurrent operations:

Don’t run multiple Ralph sessions simultaneously.

  1. Increase iteration timeout:

Give agent more time to work without rushing:

{
  "agentTimeoutMs": 3600000
}

Getting Help

If your issue isn’t listed here:

1. Check Logs

# Latest log
tail -f ~/.ralph/projects/<project>/logs/latest.log

# All logs
ls ~/.ralph/projects/<project>/logs/

# Search for errors
grep -i error ~/.ralph/projects/<project>/logs/*.log

2. Search GitHub Issues

Ralph GitHub Issues

Search for your error message or symptoms.

3. Open a New Issue

Include:

  • Ralph version: ralph --version
  • Agent being used: From ralph config
  • Operating system: uname -a
  • Error message: Full error text
  • Steps to reproduce: What you did before the error
  • Logs: Relevant log excerpts

4. Community Support

  • GitHub Discussions
  • Discord (if available)
  • Stack Overflow with ralph-cli tag

Next Steps