Skip to content

Troubleshooting

Common issues and their solutions when using gh-worker.

Installation Issues

Command Not Found: ghw

Symptom: Running ghw returns "command not found"

Solution:

  1. Verify installation:
uv pip list | grep gh-worker
  1. Ensure Python's script directory is in PATH:
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc
  1. Reinstall if needed:
# Install with uv
uv tool install https://github.com/tomzxcode/gh-worker.git

GitHub CLI Not Authenticated

Symptom: Errors mentioning "authentication required" or "not logged in"

Solution:

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

# If needed, refresh authentication
gh auth refresh

Claude Code CLI Not Found

Symptom: "claude-code: command not found" or agent validation errors

Solution:

  1. Install Claude Code CLI from claude.ai/code

  2. Verify installation:

claude-code --version
  1. If installed but not in PATH, specify the full path:
ghw config agent.claude_code_path /full/path/to/claude-code
  1. Or use a different agent:
ghw config agent.default opencode

Configuration Issues

Configuration File Not Found

Symptom: "Configuration file not found" errors

Solution:

# Create config directory
mkdir -p ~/.config/gh-worker

# Initialize configuration
ghw config issues-path ~/gh-worker/issues
ghw config repository-path ~/gh-worker/repos

Invalid Configuration Values

Symptom: Validation errors when setting config values

Solution:

# Check current value
ghw config plan.parallelism

# Set valid value (>= 1)
ghw config plan.parallelism 1

# For paths, use absolute paths or ~
ghw config issues-path ~/gh-worker/issues  # Good
ghw config issues-path ./issues           # May cause issues

Permission Denied on Config Directory

Symptom: Can't write to ~/.config/gh-worker

Solution:

# Fix permissions
mkdir -p ~/.config/gh-worker
chmod 755 ~/.config/gh-worker

# Or use a custom config path
ghw --config-path /writable/path/config.yaml sync --repo owner/repo

Sync Issues

No Issues Synced

Symptom: ghw sync completes but no issues are stored

Causes and Solutions:

  1. No open issues in repository:
# Check repository has issues
gh issue list --repo owner/repo
  1. Wrong repository name:
# Verify repository exists and you have access
gh repo view owner/repo
  1. Time filter too restrictive:
# Try without --since
ghw sync --repo owner/repo

# Or use longer timeframe
ghw sync --repo owner/repo --since 30d
  1. Search query excludes all issues:
# Verify search query
gh issue list --repo owner/repo --search "your-search-query"

Rate Limiting

Symptom: "API rate limit exceeded" errors

Solutions:

  1. Reduce sync frequency:
ghw config sync.frequency 1h  # Sync less often
  1. Reduce parallelism:
ghw config plan.parallelism 1
  1. Use time-based sync:
ghw sync --repo owner/repo --since 1d  # Only recent issues
  1. Check rate limit status:
gh api rate_limit

Repository Clone Failed

Symptom: Errors during repository cloning

Solutions:

  1. Verify access:
gh repo view owner/repo
  1. Check disk space:
df -h ~/gh-worker/repos
  1. Remove and re-clone:
rm -rf ~/gh-worker/repos/owner/repo
ghw add owner/repo

Plan Generation Issues

Plans Not Generated

Symptom: ghw plan completes but no plans are created

Causes and Solutions:

  1. No issues to plan:
# Verify issues exist
ls ~/gh-worker/issues/owner/repo/
  1. Plans already exist:
# Check for existing plans
find ~/gh-worker/issues/owner/repo -name "plan-*.md"

# Force regenerate by deleting old plans
rm ~/gh-worker/issues/owner/repo/42/plan-*.md
ghw plan --repo owner/repo --issue-numbers 42
  1. Agent not available:
# Verify agent
claude-code --version

# Or switch agent
ghw config agent.default claude-code

Plan Generation Hangs

Symptom: Plan generation starts but never completes

Solutions:

  1. Check agent is responsive:
claude-code --version

  1. Check network connectivity (for cloud agents)

  2. Monitor logs:

ghw --log-level DEBUG plan --repo owner/repo
  1. Reduce parallelism:
ghw plan --repo owner/repo --parallelism 1

Plan Quality Issues

Symptom: Generated plans are incomplete or incorrect

Solutions:

  1. Ensure issue descriptions are detailed:

  2. Include clear problem statement

  3. Provide reproduction steps

  4. Add context about the codebase

  5. Regenerate with more context:

# Delete old plan
rm ~/gh-worker/issues/owner/repo/42/plan-*.md

# Add more context to issue description
gh issue edit 42 --body "..." --repo owner/repo

# Resync and replan
ghw sync --repo owner/repo --issue-numbers 42
ghw plan --repo owner/repo --issue-numbers 42

Implementation Issues

Implementation Fails Immediately

Symptom: ghw implement fails right after starting

Causes and Solutions:

  1. No plan exists:
# Generate plan first
ghw plan --repo owner/repo --issue-numbers 42
  1. Repository not clean:
cd ~/gh-worker/repos/owner/repo
git status
git stash  # Or commit changes
  1. Agent not available:
claude-code --version

Implementation Hangs

Symptom: Implementation starts but never completes

Solutions:

  1. Monitor in another terminal:
ghw monitor --repo owner/repo --issue-number 42
  1. Check agent process:
ps aux | grep claude-code
  1. Check repository state:
cd ~/gh-worker/repos/owner/repo
git status
git log --oneline -5
  1. Increase timeout (if configurable):
# Implementation-specific timeout configuration

Tests Fail During Implementation

Symptom: Implementation fails because tests don't pass

Solutions:

  1. Review test output in agent logs

  2. Run tests manually:

cd ~/gh-worker/repos/owner/repo
pytest  # Or your test command
  1. Fix test issues and retry:
# Fix tests
ghw implement --repo owner/repo --issue-numbers 42

Branch Already Exists

Symptom: "Branch already exists" error

Solutions:

cd ~/gh-worker/repos/owner/repo

# Option 1: Delete existing branch
git branch -D issue-42-branch-name
git push origin --delete issue-42-branch-name

# Option 2: Check out and update existing branch
git checkout issue-42-branch-name

Pull Request Creation Failed

Symptom: Implementation succeeds but PR creation fails

Solutions:

  1. Verify GitHub CLI permissions:
gh auth status
  1. Check repository permissions:
gh repo view owner/repo
  1. Create PR manually:
cd ~/gh-worker/repos/owner/repo
gh pr create --title "Fix issue #42" --body "..."

Monitoring Issues

Monitor Shows No Output

Symptom: ghw monitor runs but shows nothing

Causes and Solutions:

  1. Wrong issue number:
# Verify issue is being implemented
ls ~/gh-worker/issues/owner/repo/42/
  1. Session not found:
# Implementation may not have started
ghw implement --repo owner/repo --issue-numbers 42
  1. Session completed:
  2. Monitor can't show output for completed sessions
  3. Check implementation results instead

Work Command Issues

Work Command Stops After One Iteration

Symptom: ghw work runs once then exits

Solution:

Remove --once flag for continuous mode:

# This runs once and exits
ghw work --once --repos owner/repo

# This runs continuously
ghw work --repos owner/repo

Work Command Frequency Not Respected

Symptom: Work command runs more/less frequently than configured

Solutions:

  1. Check configuration:
ghw config sync.frequency
  1. Specify frequency explicitly:
ghw work --repos owner/repo --frequency 30m
  1. Monitor logs to verify timing:
ghw --log-level DEBUG work --repos owner/repo

Performance Issues

Slow Execution

Causes and Solutions:

  1. Low parallelism:
ghw config plan.parallelism 3
ghw config implement.parallelism 2

  1. Network latency:

  2. Check internet connection

  3. Use closer/faster agent endpoints

  4. Large repository:

  5. Repository cloning and operations take longer

  6. Consider shallow clones (if implemented)

  7. Resource constraints:

# Check system resources
top
df -h

High Memory Usage

Solutions:

  1. Reduce parallelism:
ghw config plan.parallelism 1
ghw config implement.parallelism 1
  1. Process issues in batches:
# Instead of all at once
ghw plan --repo owner/repo --issue-numbers 1 2 3
ghw plan --repo owner/repo --issue-numbers 4 5 6

File System Issues

Disk Space Full

Symptom: "No space left on device" errors

Solutions:

  1. Check disk space:
df -h ~/gh-worker
  1. Clean old plans:
find ~/gh-worker/issues -name "plan-*.md" -mtime +30 -delete
  1. Remove old repositories:
rm -rf ~/gh-worker/repos/unused-repo
  1. Move to larger disk:
ghw config issues-path /larger-disk/gh-worker/issues
ghw config repository-path /larger-disk/gh-worker/repos

Permission Denied

Symptom: Can't read/write files in gh-worker directories

Solutions:

# Fix ownership
sudo chown -R $USER:$USER ~/gh-worker

# Fix permissions
chmod -R u+rwX ~/gh-worker

Logging and Debugging

Enable Debug Logging

For detailed troubleshooting:

ghw --log-level DEBUG <command>

View Recent Logs

# View structured logs
ghw --log-level DEBUG sync --repo owner/repo 2>&1 | less

Check Agent Logs

Agent-specific logs may be in different locations:

# Claude Code (example)
# Check agent documentation for log location

Getting Help

If you can't resolve your issue:

  1. Check existing issues: GitHub Issues

  2. Create a new issue with:

  3. gh-worker version

  4. Python version
  5. Operating system
  6. Complete error message
  7. Steps to reproduce

  8. Debug logs

  9. Include diagnostics:

# System info
python --version
ghw --version
gh --version
claude-code --version  # If using Claude Code

# Configuration
ghw config issues-path
ghw config repository-path
ghw config agent.default

Next Steps