Troubleshooting

This guide covers common problems you might encounter and how to solve them.

Authentication Errors

Bad Credentials

Error Message:

AuthenticationError: GitHub authentication failed
Check your GITHUB_TOKEN in .env file.

Cause: Your GitHub token is invalid, expired, or incorrect. Solution:

Generate a new token

Go to GitHub Settings > Developer settings > Personal access tokens
Click Generate new token → Generate new token (classic)
Select the repo scope (full control of private repositories)
Copy the token immediately

Update your .env file

Open .env in your project root:

GITHUB_TOKEN=ghp_your_new_token_here

Restart the CLI

npm start

Insufficient Permissions

Error Message:

InsufficientPermissionsError: Cannot write on your-username/your-repo
Your token needs additional permissions.

Cause: Your token doesn’t have the required scopes. Solution:

Check token scopes: Go to Settings > Developer settings > Personal access tokens
Required scopes:
- ✅ repo - Full control of private repositories
- ✅ write:discussion - For Galaxy Brain (if using)
Regenerate the token if scopes are missing
Update .env with the new token

You cannot add scopes to an existing token. You must generate a new token with the correct scopes.

Resource Not Accessible

Error Message:

GitHubAPIError (403): Resource not accessible by integration

Cause: The token doesn’t have access to the repository or resource. Common Scenarios:

Private Repository

If your target repository is private:

Ensure your token has the repo scope (not just public_repo)
Verify you own the repository or have write access
If using a helper account, add it as a collaborator

Organization Repository

If the repository belongs to an organization:

Check if the organization requires SSO authorization
Go to Settings > Personal access tokens
Find your token and click Configure SSO
Authorize it for the organization

Discussions Not Enabled

For Galaxy Brain:

Go to repository Settings > Features
Enable ✅ Discussions
Wait a moment for the feature to activate

Rate Limit Errors

Rate Limit Exceeded

Error Message:

RateLimitError: GitHub API rate limit exceeded. Resets in 45 minutes.

Cause: You’ve exceeded GitHub’s API rate limits. GitHub’s Limits:

Authenticated requests: 5,000 per hour
Content-creating requests: 80 per minute
Secondary rate limits: 2 concurrent requests (for writes)

What the CLI Does: The CLI automatically rate limits itself to stay under GitHub’s limits:

Max concurrent operations: 2
Operations per minute: 15 (× 5 API calls = 75, under 80 limit)

From src/utils/rateLimiter.ts:9-20:

// Each operation makes ~5 API calls (branch, commit, PR, merge, delete)
// GitHub's limit is 80 content-creating requests/minute
// We limit to 15 operations/minute (75 API calls) to stay safe
const DEFAULT_CONFIG: RateLimiterConfig = {
  maxPerMinute: 15,
  maxConcurrent: 2,
  backoffBaseMs: 1000,
};

Solutions:

Wait for reset

The easiest solution is to wait. GitHub rate limits reset every hour (or every minute for secondary limits).The CLI will tell you how long to wait:

Wait 45 minutes before retrying

Reduce concurrency

If you’re hitting secondary rate limits, reduce concurrent operations in your config (if you’ve customized it).

Resume later

Press Ctrl+C to stop. Your progress is saved. Resume after the rate limit resets:

npm start
# Select "Run Achievements" and choose the same achievement

The CLI automatically retries with exponential backoff when it hits rate limits. You usually don’t need to do anything.

Secondary Rate Limit

Error Message:

You have exceeded a secondary rate limit

Cause: GitHub detected too many concurrent write operations. Solution: The CLI already limits concurrent operations to 2, but if you still hit this:

Wait 1 minute - Secondary rate limits reset quickly
The CLI will retry automatically with exponential backoff
Don’t restart - Let it handle the retry

From src/utils/rateLimiter.ts:138-148:

handleRateLimitError(retryAfter?: number, attempt: number = 1): number {
  if (retryAfter) {
    return retryAfter * 1000;
  }
  
  // Exponential backoff with jitter
  const baseDelay = this.config.backoffBaseMs;
  const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
  const jitter = Math.random() * 1000;
  return Math.min(exponentialDelay + jitter, 60000); // Cap at 60 seconds
}

Repository Errors

Repository Not Found

Error Message:

RepositoryNotFoundError: Repository not found: your-username/your-repo

Cause: The repository doesn’t exist or your token can’t access it. Solutions:

Verify the repository exists

Go to https://github.com/your-username/your-repo in your browser. Does it load?

Check the repository name format

It must be in the format owner/repo:✅ Correct: alice/test-achievements
❌ Wrong: test-achievements
❌ Wrong: alice/test-achievements.git

Update .env if needed

TARGET_REPO=your-username/your-repo

Check token access

If the repo is private, ensure your token has the repo scope (not just public_repo).

No Write Access

Error Message:

NoWriteAccessError: No write access to repository: your-username/your-repo

Cause: You don’t have push permission to the repository. Solutions:

If you own the repo: Regenerate your token with the repo scope
If it’s someone else’s repo: You need to be added as a collaborator with write access
Fork the repo: Create your own fork and use that as the target

Discussions Not Enabled

Error Message:

DiscussionsNotEnabledError: Discussions are not enabled for repository

Cause: Galaxy Brain requires GitHub Discussions, but it’s not enabled on your repository. Solution:

Go to repository settings

Navigate to your target repository on GitHub and click Settings.

Enable Discussions

Scroll to the Features section
Check ✅ Discussions
Click Set up discussions if prompted

Wait and retry

Wait 30 seconds for the feature to activate, then try running Galaxy Brain again.

Operation Errors

Branch Already Exists

Error Message:

BranchExistsError: Branch already exists: pair-extraordinaire-1

Cause: A branch with that name already exists, likely from a previous interrupted run. Solutions:

Delete the branch manually

cd /path/to/your/repo
git push origin --delete pair-extraordinaire-1

Delete all achievement branches

# List achievement branches
git branch -r | grep "origin/pair-extraordinaire\|origin/pull-shark\|origin/galaxy-brain"

# Delete them
git branch -r | grep "origin/pair-extraordinaire\|origin/pull-shark\|origin/galaxy-brain" | sed 's/origin\///' | xargs -I {} git push origin --delete {}

Retry the operation

The CLI should now be able to create the branch.

Branches are automatically deleted after PRs merge. If you see leftover branches, it means a previous run was interrupted before cleanup completed.

Merge Conflict

Error Message:

MergeConflictError: Pull request #123 has merge conflicts

Cause: The PR branch has conflicts with the base branch. Why This Happens:

Rarely occurs during normal operation
Usually indicates concurrent operations modified the same files
Most common if you manually modified the repository during execution

Solution: The operation will be marked as failed, but other operations continue. The CLI will report the failure at the end:

Results:
✓ 47 succeeded
✗ 1 failed

You can:

Accept the failure - 47/48 is usually enough for the achievement
Run again - The CLI will skip completed operations and retry the failed one

PR Already Merged

Error Message:

PRAlreadyMergedError: Pull request #123 is already merged

Cause: The operation tried to merge a PR that was already merged. Solution: This is usually harmless. The CLI will mark the operation as complete and continue. If you see this:

It’s likely a resume scenario where the PR was merged but the database wasn’t updated
The operation will be counted as successful
No action needed

Network Errors

Connection Timeout

Error Message:

NetworkError: Network request failed
Check your internet connection and try again.

Causes:

Internet connection issues
GitHub API is down
Firewall blocking requests
Proxy configuration issues

Solutions:

Check internet connection

ping github.com

If this fails, your internet is down or GitHub is unreachable.

Check GitHub status

Visit githubstatus.com to see if GitHub is experiencing issues.

Check proxy settings

If you’re behind a corporate proxy:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Then run the CLI
npm start

Retry later

If GitHub is down or your connection is unstable, wait and try again. Your progress is saved.

DNS Resolution Failed

Error Message:

getaddrinfo ENOTFOUND api.github.com

Cause: DNS cannot resolve GitHub’s domain. Solutions:

Check DNS servers: Try using Google DNS (8.8.8.8) or Cloudflare DNS (1.1.1.1)

Flush DNS cache:

# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns

Check /etc/hosts: Ensure api.github.com isn’t blocked

Database Errors

Database Error During Operation

Error Message:

DatabaseError: Database error during save: EACCES permission denied

Cause: The CLI can’t read or write the database file. Solutions:

Check file permissions

ls -la achievements-data-*.json

Ensure you have read and write permissions.

Fix permissions

chmod 644 achievements-data-*.json

Check disk space

df -h .

Ensure you have available disk space.

Delete and restart (last resort)

If the database is corrupted:

# Back up first
cp achievements-data-*.json achievements-data-backup.json

# Delete corrupted database
rm achievements-data-*.json

# Restart CLI (creates new database)
npm start

⚠️ This will lose progress tracking, but you can re-run achievements.

Configuration Errors

Missing Configuration

Error Message:

MissingConfigError: Missing required configuration: GITHUB_TOKEN

Cause: Required environment variables are not set in .env. Solution:

Check if .env exists

ls -la .env

If it doesn’t exist, create it:

touch .env

Add required configuration

Open .env and add:

GITHUB_TOKEN=ghp_your_token_here
GITHUB_USERNAME=your-username
TARGET_REPO=your-username/your-repo

Restart the CLI

npm start

Configuration Error

Error Message:

ConfigurationError: Configuration error for TARGET_REPO: invalid format

Cause: A configuration value is invalid. Common Issues:

Field	Wrong	Correct
TARGET_REPO	`my-repo`	`username/my-repo`
TARGET_REPO	`github.com/user/repo`	`user/repo`
GITHUB_TOKEN	(missing)	`ghp_xxx...`
GITHUB_USERNAME	(spaces)	`no-spaces-allowed`

Stuck Operations

Operations Stuck in “In Progress”

Symptom: Some operations show as “in_progress” in the status view, but nothing is running. Cause: The CLI was interrupted (Ctrl+C or crash) while operations were running. Solution: This is handled automatically! When you run the achievement again, stuck operations are reset: From src/achievements/base.ts:109-113:

// Reset any stuck 'in_progress' operations from previous interrupted runs
const resetCount = resetStuckOperations(this.achievementId);
if (resetCount > 0) {
  logger.info(`Reset ${resetCount} stuck operations from previous run`);
}

Just run the achievement again:

npm start
# Select "Run Achievements" and choose the same achievement

The CLI will:

Detect stuck operations
Reset them to “pending”
Retry them

Getting Help

If you encounter an error not covered here:

1. Check Error Details

The CLI provides error codes and suggestions:

AuthenticationError: GitHub authentication failed
Code: AUTH_FAILED
Suggestion: Check your GITHUB_TOKEN in .env file.

Follow the suggestion first.

2. Check Logs

The CLI logs detailed information. Look for error messages and stack traces in the terminal output.

3. Common Patterns

Authentication Issues

Bad credentials → Regenerate token
Insufficient permissions → Add repo scope
Resource not accessible → Check repository access

Rate Limits

Rate limit exceeded → Wait for reset (shown in error)
Secondary rate limit → Wait 1 minute, retry automatically

Network Issues

Connection timeout → Check internet connection
DNS failed → Check DNS settings
GitHub down → Wait and retry later

Database Issues

Permission denied → Fix file permissions
Corrupted → Delete and recreate
Disk full → Free up space

4. File an Issue

If you’ve tried everything and still have issues:

Go to the GitHub repository issues page
Search for similar issues
If none found, create a new issue with:
- Error message (full text)
- Steps to reproduce
- Your environment (OS, Node.js version)
- CLI output (sanitize tokens!)

Never share your GitHub tokens in issues or public forums! Always redact them from logs and screenshots.

Prevention Tips

Best Practices to Avoid Issues

Use a test repository - Don’t use a repository with important code
Check token scopes - Ensure repo scope is selected when generating tokens
Verify repository access - Make sure you own or have write access to the target repo
Don’t interrupt during critical operations - Let operations complete when possible
Keep tokens secure - Never commit .env to version control
Monitor rate limits - Don’t manually trigger operations while the CLI is running
Use latest version - Update the CLI regularly: git pull && npm install

Health Check Before Running

Before running achievements, verify:

# Check token is set
grep GITHUB_TOKEN .env

# Check repository exists
curl -H "Authorization: token $(grep GITHUB_TOKEN .env | cut -d= -f2)" \
  https://api.github.com/repos/your-username/your-repo

# Should return repository JSON, not 404

Get Started

Configuration

Achievements

Guides

Authentication Errors

Bad Credentials

Insufficient Permissions

Resource Not Accessible

Rate Limit Errors

Rate Limit Exceeded

Secondary Rate Limit

Repository Errors

Repository Not Found

No Write Access

Discussions Not Enabled

Operation Errors

Branch Already Exists

Merge Conflict

PR Already Merged

Network Errors

Connection Timeout

DNS Resolution Failed

Database Errors

Database Error During Operation

Configuration Errors

Missing Configuration

Configuration Error

Stuck Operations

Operations Stuck in “In Progress”

Getting Help

1. Check Error Details

2. Check Logs

3. Common Patterns

4. File an Issue

Prevention Tips

Best Practices to Avoid Issues

Health Check Before Running

Build docs developers (and LLMs) love

Get Started

Configuration

Achievements

Guides

​Authentication Errors

​Bad Credentials

​Insufficient Permissions

​Resource Not Accessible

​Rate Limit Errors

​Rate Limit Exceeded

​Secondary Rate Limit

​Repository Errors

​Repository Not Found

​No Write Access

​Discussions Not Enabled

​Operation Errors

​Branch Already Exists

​Merge Conflict

​PR Already Merged

​Network Errors

​Connection Timeout

​DNS Resolution Failed

​Database Errors

​Database Error During Operation

​Configuration Errors

​Missing Configuration

​Configuration Error

​Stuck Operations

​Operations Stuck in “In Progress”

​Getting Help

​1. Check Error Details

​2. Check Logs

​3. Common Patterns

​4. File an Issue

​Prevention Tips

​Best Practices to Avoid Issues

​Health Check Before Running

Build docs developers (and LLMs) love

Authentication Errors

Bad Credentials

Insufficient Permissions

Resource Not Accessible

Rate Limit Errors

Rate Limit Exceeded

Secondary Rate Limit

Repository Errors

Repository Not Found

No Write Access

Discussions Not Enabled

Operation Errors

Branch Already Exists

Merge Conflict

PR Already Merged

Network Errors

Connection Timeout

DNS Resolution Failed

Database Errors

Database Error During Operation

Configuration Errors

Missing Configuration

Configuration Error

Stuck Operations

Operations Stuck in “In Progress”

Getting Help

1. Check Error Details

2. Check Logs

3. Common Patterns

4. File an Issue

Prevention Tips

Best Practices to Avoid Issues

Health Check Before Running