Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
344 lines (237 loc) · 7.2 KB

TROUBLESHOOTING.md

File metadata and controls

344 lines (237 loc) · 7.2 KB
Raw

Troubleshooting Guide

Common issues and solutions when using Repatch.

Installation Issues

repatch: command not found

Cause: Binary not in PATH after one-line install.

Fix:

# Linux/macOS - add to PATH
export PATH="$HOME/.local/bin:$PATH"
# Or restart your shell

# Windows - add to PATH via System Properties > Environment Variables

Permission denied on install.sh

Cause: Script not executable.

Fix:

chmod +x install.sh
./install.sh

Homebrew: Error: No available formula

Cause: Tap not added or outdated.

Fix:

brew tap Sagar-024/repatch
brew update
brew install repatch

Configuration Issues

repatch check fails

Common causes:

Check Fix
Docker not running Start Docker Desktop, or use --local flag
No LLM provider configured Run repatch configure or set env vars
GitHub token invalid Check GH_TOKEN or .repatch.yaml
Node.js version < 20 Upgrade Node.js

No model configured

Cause: No default model set and no --model flag.

Fix:

repatch configure  # Interactive setup
# OR
export AI_MODEL=gpt-4o

API key errors

Error: Invalid API key

Fix:

  • Verify key in .repatch.yaml or environment variable
  • Check key has correct permissions (OpenAI: gpt-4o access)
  • Ensure no extra whitespace in config file

Runtime Issues

Docker: Cannot connect to the Docker daemon

Cause: Docker not running or no permission.

Fix:

# Start Docker Desktop (macOS/Windows)
# Linux: sudo systemctl start docker

# Or run without Docker:
repatch fix <url> -i "issue" --local

Docker: no space left on device

Cause: Docker disk full.

Fix:

docker system prune -a  # Remove unused images/containers
# Or increase Docker disk limit in Docker Desktop settings

Sandbox: npm install fails in container

Cause: Network disabled or registry issues.

Fix:

# Enable network in config:
# .repatch.yaml
sandbox:
  network: true

# Or use --local mode with host network
repatch fix <url> -i "issue" --local

Local mode: command not found (node, python, go, etc.)

Cause: Language runtime not installed on host.

Fix:

# Install required runtime:
# Node.js: https://nodejs.org/
# Python: https://python.org/
# Go: https://golang.org/dl/
# Rust: https://rustup.rs/

Local mode: permission denied on dependency install

Cause: No write permission in repo directory.

Fix:

# Ensure you own the repo directory
sudo chown -R $USER:$USER /path/to/repo

# Or run with proper permissions

LLM / Provider Issues

Rate limit exceeded / 429 Too Many Requests

Cause: API rate limit hit.

Fix:

  • Wait and retry
  • Use a different provider: --model claude-3-5-sonnet-latest
  • Add budget limit to slow down: --budget 0.10

Token limit exceeded / Context length exceeded

Cause: Issue + codebase too large for model context.

Fix:

  • Use model with larger context (GPT-4o: 128k, Claude: 200k)
  • Narrow issue scope with -h "hint" to focus exploration
  • Split large repos into smaller modules

Prompt injection detected / Input validation failed

Cause: Issue text contains patterns flagged by sanitizer.

Fix:

  • Simplify issue description
  • Avoid code-like patterns in issue text
  • Report false positives on GitHub

Gemini: Failed to parse tool call

Cause: Gemini CLI output format changed.

Fix:

  • Update to latest version: npm install -g @google/generative-ai
  • Or use Gemini API instead: set gemini.apiKey in config

Execution Issues

Tests still failing after fix (backtrack loop)

Cause: Fix didn't address root cause, or test is flaky.

What happens: Repatch automatically backtracks VERIFY → PLAN → EXECUTE up to 3 times.

If stuck:

  • Check --budget not exhausted
  • Add hint: -h "Focus on X module"
  • Run repatch reproduce first to verify reproduction

Edit failed: fuzzy match not found

Cause: LLM's edit snippet doesn't match source code.

Fix:

  • Run repatch explore to verify file contents
  • Add more specific hint: -h "File is src/auth/middleware.ts"
  • Check for whitespace/encoding issues in source

Git push failed in SUBMIT step

Cause: No GitHub token, or token lacks repo scope.

Fix:

# Ensure token has repo scope
# GitHub Settings > Developer settings > Personal access tokens > repo
export GH_TOKEN=ghp_...

PR already exists / Branch already exists

Cause: Previous run created same branch.

Fix:

# Clean up remote branch
git push origin --delete repatch/fix-<issue-hash>

# Or let Repatch handle it (auto-generates unique branch names)

Performance Issues

Slow execution

Typical causes:

  • Large repo (many files to scan)
  • Slow LLM provider
  • Docker image build on first run

Mitigations:

# Use local mode (faster startup)
repatch fix <url> -i "issue" --local

# Use faster model
repatch fix <url> -i "issue" --model gpt-4o-mini

# Limit exploration scope
repatch fix <url> -i "issue" -h "Only look at src/api/"

High costs

Monitor: repatch fix --budget 0.50 enforces hard limit.

Reduce:

  • Use cheaper model: gpt-4o-mini, gemini-1.5-flash
  • Narrow hints to reduce exploration
  • Fix one issue at a time (not fix-multi)

Debugging

Enable debug logging

DEBUG=1 repatch fix <url> -i "issue"

Shows:

  • LLM prompts/responses (truncated)
  • Tool calls with arguments
  • State transitions
  • Sandbox commands

Inspect checkpoint

# After crash or --resume
cat .repatch-checkpoint.json

Contains:

  • currentStep — where it stopped
  • visitedFiles — what was explored
  • issue — original issue text
  • cost — accumulated spend

Reproduce without fixing

repatch reproduce <url> -i "issue"

Read-only, stops after REPRODUCE step. Useful for verifying bug exists.

Explore codebase first

repatch explore . -q "How does authentication work?"

Understand codebase before running fix loop.

Common Error Codes

Error Meaning Action
ENOENT: no such file File not found in sandbox Check path, use --local
EACCES: permission denied Write permission issue Fix file permissions
ETIMEDOUT Sandbox command timeout Increase timeout, simplify test
ZOD_VALIDATION_ERROR Config/schema invalid Run repatch configure
GITHUB_API_ERROR GitHub API failed Check token, rate limits

Getting Help

  1. Check logs with DEBUG=1
  2. Search issues — GitHub Issues
  3. Open new issue with:
    • Command run
    • Full error output
    • repatch check output
    • .repatch-checkpoint.json (if applicable)

Known Workarounds

Issue Workaround
Docker not available Use --local flag
Gemini CLI parsing fails Use Gemini API key instead
Large repo context overflow Add specific -h hint
Flaky tests cause backtrack loop Fix test in repo, or increase --budget
Windows path issues in Docker Use --local or WSL2