mcp-github-error-recovery

name	mcp-github-error-recovery
description	GitHub MCP error handling and recovery procedures
user-invocable	false
triggers	{"require-any":["mcp:github"],"priority":80,"ttl":"session"}

GitHub MCP Error Recovery

This skill provides error handling and recovery procedures for GitHub MCP tool usage.

Common Error Patterns

Authentication Failures (401 Unauthorized)

Symptoms:

• mcp__github__* tools return "Bad credentials"
• Response includes "Requires authentication"
• 401 status code in error message

Root Causes:

1. GITHUB_TOKEN environment variable not set
2. Token has expired
3. Token lacks required scopes for the operation
4. Token has been revoked

Resolution Steps:

1. Check token existence:

   # Verify GITHUB_TOKEN is set (don't echo the value)
   [[ -n "$GITHUB_TOKEN" ]] && echo "Token is set" || echo "Token is missing"
   

2. Verify token scopes:

   • Required scopes for common operations:
     • Read public repos: no scopes needed (but token must exist)
     • Read private repos: repo scope
     • Create issues/PRs: repo scope
     • Modify workflows: workflow scope

3. Alert operator if token is invalid:

   • DO NOT attempt to regenerate tokens automatically
   • Message: "GitHub API authentication failed. Please check GITHUB_TOKEN environment variable and ensure it has required scopes: [list scopes needed for the operation]"

Prevention:

• Token should be stored in .claude/.env (gitignored) or system environment
• Never commit tokens to repository
• Use minimal required scopes

---

Rate Limiting (403 Forbidden)

Symptoms:

• mcp__github__* tools return "API rate limit exceeded"
• Response includes rate limit information
• 403 status code with rate limit headers

Understanding GitHub Rate Limits:

• Authenticated requests: 5,000/hour
• Search API: 30 requests/minute
• Unauthenticated: 60/hour (very low)

Resolution Steps:

1. Immediate response:

   • STOP making GitHub API calls
   • Wait 60 seconds before retrying the failed operation

2. Check rate limit status (if available):

   Use mcp__github__get_rate_limit if the tool exists
   

3. Optimize remaining operations:

   • Batch multiple file reads into fewer calls
   • Use more specific search queries to reduce result sets
   • Consider if operation is truly necessary or can be deferred

4. Backoff schedule:

   Attempt	Wait Time	Action
   1st limit hit	60 seconds	Retry with batched operations
   2nd limit hit	120 seconds	Retry only critical operations
   3rd limit hit	Alert operator	Do not retry automatically

Prevention:

• Use authenticated requests (much higher limit)
• Minimize API calls by reading local files when possible
• Cache results when appropriate
• Use search filters to reduce result sets

---

Not Found (404)

Symptoms:

• mcp__github__get_file_contents returns "Not Found"
• Repository or file path doesn't exist
• 404 status code

Common Causes:

1. Incorrect file path:

   • Case sensitivity matters (README.md ≠ readme.md)
   • Path separators must be forward slashes
   • No leading slash in file paths

2. Wrong branch:

   • Default branch might be master not main
   • File exists on different branch

3. Access issues:

   • Repository is private and token lacks access
   • Repository was deleted or renamed
   • Organization permissions don't allow access

Resolution Steps:

1. Verify repository exists:

   Try listing repository contents first to confirm access
   

2. Check branch name:

   • Don't assume default branch is "main"
   • List branches to find correct one

3. Verify file path:

   • Try listing parent directory first
   • Check for spelling and case

4. Validate access:

   • Confirm repository owner and name are correct
   • Ensure token has repo scope if repository is private

Prevention:

• Always validate repository existence before attempting file operations
• Check branch name first (don't assume)
• Use relative paths within repository

---

Network Errors (Timeouts, Connection Refused)

Symptoms:

• "timeout" in error message
• "ECONNREFUSED" or "ETIMEDOUT"
• Network connectivity issues

Resolution Steps:

1. Immediate retry:

   • Single network failure is often transient
   • Wait 5 seconds and retry once

2. Exponential backoff:

   Attempt	Wait	Action
   1st	5s	Immediate retry
   2nd	15s	Retry with longer timeout
   3rd	45s	Final retry
   4th	Alert	Do not retry

3. Check GitHub status:

   • Alert operator: "GitHub API is experiencing connectivity issues. You may want to check https://www.githubstatus.com"

Prevention:

• Build retry logic into critical operations
• Have fallback strategies for when GitHub is unavailable

---

Server Errors (500, 502, 503)

Symptoms:

• "Internal server error"
• "Bad gateway"
• "Service unavailable"
• 5xx status codes

Resolution Steps:

1. This is GitHub's problem, not ours:

   • 500-level errors indicate GitHub server issues
   • No action on our side will fix this

2. Retry strategy:

   • Wait 30 seconds and retry once
   • If second attempt fails, alert operator
   • Do not retry more than twice

3. Alert operator:

   • "GitHub API returned server error. This indicates an issue on GitHub's side. Operation: [describe operation]. You may want to check https://www.githubstatus.com"

Prevention:

• Have fallback strategies for when GitHub is degraded
• Don't build critical paths that require GitHub to always be available

---

Tool-Specific Best Practices

Creating Pull Requests

Always verify preconditions:

1. Branch exists and has commits:

   Use mcp__github__list_commits to verify branch has commits
   

2. No existing PR for this branch:

   Use mcp__github__list_pull_requests to check for existing PRs from this branch
   

3. Branch is ahead of base:

   • Ensure there are actual changes to merge
   • Avoid creating empty PRs

Common errors:

• "A pull request already exists" → Check existing PRs first
• "No commits between base and head" → Branch has no unique commits

---

Searching Code

Performance optimization:

1. Use narrow queries:

   • Include language filter: language:python
   • Include path filter: path:src/
   • Use specific search terms, not broad ones

2. Limit result set:

   Set per_page: 10 or less for exploratory searches
   

3. Search API has strict rate limits:

   • Only 30 requests per minute
   • Use search sparingly
   • Consider alternatives (grep local clone)

---

Getting File Contents

Best practices:

1. Always specify branch:

   • Don't rely on default branch assumption
   • Explicitly pass branch parameter

2. Handle binary files:

   • GitHub API returns base64 for binary files
   • Check file extension before requesting

3. Large files:

   • Files > 1MB may fail or return truncated
   • Consider cloning repository for large files

---

Credential Management

Token Storage

Recommended: Store in .claude/.env (gitignored):

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Required Token Scopes:

Operation	Required Scope
Read public repos	None (but token must exist)
Read private repos	repo
Create issues	repo or public_repo
Create PRs	repo
Modify GitHub Actions	workflow
Read organization data	read:org

Token Rotation

When token expires or is revoked:

1. DO NOT attempt automatic rotation

   • Alert operator immediately
   • Provide clear error message
   • Stop attempting GitHub operations

2. Operator action required:

   • Generate new token at https://github.com/settings/tokens
   • Update .claude/.env with new token
   • Restart session or reload environment

---

Error Recovery Decision Tree

GitHub MCP tool fails
    |
    +-- 401/403 auth error?
    |       |
    |       +-- Check GITHUB_TOKEN exists
    |       +-- Alert operator about scopes/expiration
    |       +-- STOP (don't retry)
    |
    +-- 403 rate limit?
    |       |
    |       +-- Wait 60 seconds
    |       +-- Optimize remaining operations
    |       +-- Retry with backoff schedule
    |
    +-- 404 not found?
    |       |
    |       +-- Verify repository exists
    |       +-- Check branch name
    |       +-- Validate file path
    |       +-- Try alternative approach
    |
    +-- Network error (timeout/refused)?
    |       |
    |       +-- Retry once after 5 seconds
    |       +-- If fails again, exponential backoff
    |       +-- After 3 attempts, alert operator
    |
    +-- 500-level server error?
            |
            +-- Wait 30 seconds
            +-- Retry once
            +-- If fails, alert operator (GitHub issue)

---

Monitoring and Logging

What to Log

For each GitHub MCP operation, log:

• Tool name
• Parameters (sanitized - no tokens)
• Success/failure
• Error type if failed
• Duration

When to Alert Operator

Immediate alert:

• Authentication failures (token invalid/expired)
• 3+ consecutive rate limits
• 3+ consecutive network failures
• Any credential-related error

Info alert:

• First rate limit hit (warning)
• GitHub server errors (5xx)
• Unexpected 404s on known resources

---

Quick Reference Card

Error Pattern	First Action	Max Retries
401 Auth	Alert operator	0 (do not retry)
403 Rate limit	Wait 60s	2 with backoff
404 Not found	Verify path/branch	1 (after validation)
Network timeout	Wait 5s	3 with exponential backoff
500 Server error	Wait 30s	1

Key Principle: When in doubt, alert the operator rather than retry indefinitely.

---

This skill is automatically injected when GitHub MCP tools are first used in a session.