GitHub Troubleshooting Guide: Common Issues & Solutions

This comprehensive troubleshooting guide covers the most common GitHub issues you'll encounter during development, contribution, and repository management. Each problem includes step-by-step solutions and preventive measures.

Authentication Issues
Repository Access Problems
Git Operations Issues
Pull Request Problems
GitHub Actions Failures
Branch and Merge Conflicts
Fork and Upstream Issues
Security and Permissions
Performance Issues
API and Integration Problems

1. Authentication Issues

Problem: "Authentication failed" when pushing

remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/user/repo.git/'

Solutions:

Check credentials:

# For HTTPS
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Switch to SSH (recommended)
git remote set-url origin git@github.com:user/repo.git

Generate new SSH key:

ssh-keygen -t ed25519 -C "your.email@example.com"
cat ~/.ssh/id_ed25519.pub  # Copy this to GitHub
ssh -T git@github.com      # Test connection

Use Personal Access Token:

# Create token at: https://github.com/settings/tokens
git remote set-url origin https://USERNAME:TOKEN@github.com/user/repo.git

Clear credential cache:

git config --global --unset credential.helper
# Or on Windows: git config --global credential.helper wincred

Problem: "Permission denied (publickey)"

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Solutions:

Verify SSH key is added to GitHub:
- Go to Settings → SSH and GPG keys
- Ensure your public key is listed

Check SSH agent:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
ssh -T git@github.com

Use correct SSH URL:

git remote set-url origin git@github.com:user/repo.git

Problem: Two-factor authentication issues

Solutions:

Use Personal Access Token instead of password

Configure Git credential helper:

git config --global credential.helper store
# Enter username and token when prompted

2. Repository Access Problems

Problem: "Repository not found"

fatal: repository 'https://github.com/user/repo.git/' not found

Solutions:

Check repository URL:

git remote -v
# Should show: origin https://github.com/OWNER/REPO.git

Verify repository exists and is public:
- Check if repository is private (need access)
- Verify spelling of owner/repo name
Check organization permissions:
- Ensure you're added to the organization
- Check if repository requires specific team membership

Problem: "You don't have permission to push to this repository"

Solutions:

Fork the repository:

gh repo fork owner/repo --clone=true
cd repo
git remote add upstream https://github.com/owner/repo.git

Create a new branch for your changes:

git checkout -b feature/my-feature
# Make changes, then push to your fork
git push origin feature/my-feature

Create PR from your fork to upstream

Problem: Repository is archived or read-only

Solutions:

Check repository status on GitHub
Contact repository owner if you need write access
Fork active repositories instead

3. Git Operations Issues

Problem: "Non-fast-forward" merge conflicts

! [rejected] main -> main (non-fast-forward)
error: failed to push some refs to 'https://github.com/user/repo.git'

Solutions:

Pull latest changes first:

git pull --rebase origin main
# Resolve any conflicts, then:
git push origin main

Force push (if you know what you're doing):
```
git push --force-with-lease origin main
```

Create a new branch:

git checkout -b new-branch
git push origin new-branch

Problem: Large file upload fails

remote: error: GH001: Large files detected.
remote: error: File file.zip is 300.00 MB; this exceeds GitHub's file size limit of 100.00 MB

Solutions:

Use Git LFS for large files:

git lfs install
git lfs track "*.zip"
git add .gitattributes
git add large-file.zip
git commit -m "Add large file"

Remove large files from history:

# Use BFG Repo-Cleaner or git-filter-repo
git filter-repo --strip-blobs-bigger-than 100M

Use releases for large assets:
- Upload large files as release assets instead of in repository

Problem: Git ignore not working

Solutions:

Check .gitignore location:
- Must be in repository root
- Check for multiple .gitignore files

Files already tracked:

git rm --cached file-to-ignore
git commit -m "Remove tracked file"

Check syntax:

# Correct patterns
*.log
/build/
!important.log  # Exception

4. Pull Request Problems

Problem: PR shows merge conflicts

Solutions:

Sync with base branch:

git checkout your-branch
git fetch upstream
git rebase upstream/main
# Resolve conflicts
git push origin your-branch --force

Merge base branch:

git checkout your-branch
git merge upstream/main
# Resolve conflicts
git push origin your-branch

Create new PR if conflicts are severe

Problem: PR checks failing

Common issues:

Linting errors:

# Run locally first
npm run lint  # JavaScript
black .       # Python

Test failures:
```
npm test
python -m pytest
```
Check GitHub Actions logs for details

Problem: PR automatically closed

Solutions:

Reopen if accidentally closed

Create new PR with updated changes:

git checkout main
git pull upstream main
git checkout -b new-feature-branch
# Reapply changes
git push origin new-feature-branch

Problem: Can't update PR branch

Solutions:

Allow maintainers to edit PR:
- Check "Allow edits from maintainers" in PR settings
Push to your fork:
```
git push origin your-branch --force
```

5. GitHub Actions Failures

Problem: Actions not running

Solutions:

Check workflow syntax:

# Common mistakes:
- Wrong indentation
- Missing required fields
- Invalid action names

Verify file location:
- Must be in .github/workflows/
- Filename should end with .yml or .yaml
Check repository settings:
- Actions enabled in repository settings
- Branch protection rules not blocking

Problem: Actions failing with permission errors

Solutions:

Check GITHUB_TOKEN permissions:

jobs:
  job-name:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write

Use repository secrets for sensitive operations

Problem: Actions running slowly

Solutions:

Add caching:

- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Use faster runners:

runs-on: ubuntu-latest  # Instead of windows-latest

Parallelize jobs:

strategy:
  matrix:
    node-version: [16, 18]

6. Branch and Merge Conflicts

Problem: Merge conflict resolution

Solutions:

Understand conflict markers:

<<<<<<< HEAD
Your changes
=======
Incoming changes
>>>>>>> branch-name

Resolve conflicts:

# Edit files to resolve conflicts
git add resolved-file
git commit

Use merge tools:

git mergetool  # Configure with your preferred tool

Problem: Branch out of sync

Solutions:

Rebase on latest:

git fetch upstream
git rebase upstream/main

Merge latest:
```
git merge upstream/main
```
Reset if needed:
```
git reset --hard upstream/main
```

7. Fork and Upstream Issues

Problem: Fork not syncing with upstream

Solutions:

Set up upstream remote:

git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git

Sync fork:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Sync all branches:

git fetch upstream
git push origin upstream/main:main

Problem: Can't push to upstream

Solutions:

You don't have push access to upstream
Always push to your fork first:
```
git push origin your-branch
```
Create PR to upstream

8. Security and Permissions

Problem: "Repository ruleset violation"

Solutions:

Check repository rules:
- Branch protection rules
- Required status checks
- Code scanning alerts
Fix security issues:
- Update dependencies
- Fix code scanning alerts
- Address Dependabot alerts

Problem: Dependabot failing

Solutions:

Check configuration:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

Fix dependency conflicts
Update to compatible versions

9. Performance Issues

Problem: Slow repository operations

Solutions:

Optimize repository size:

# Remove large files
git filter-repo --strip-blobs-bigger-than 100M

# Clean up
git gc --aggressive --prune=now

Use shallow clones:

git clone --depth 1 https://github.com/user/repo.git

Enable Git LFS for large assets

Problem: GitHub Pages not updating

Solutions:

Wait for build (can take 10-20 minutes)
Check build status in repository settings
Verify source branch and folder
Check for Jekyll build errors

10. API and Integration Problems

Problem: GitHub API rate limiting

Solutions:

Use authentication:
```
export GITHUB_TOKEN=your_token
```

Implement retry logic:

import time
import requests

def api_call(url):
    response = requests.get(url, headers={'Authorization': f'token {token}'})
    if response.status_code == 403:
        time.sleep(60)  # Wait for rate limit reset
        return api_call(url)
    return response

Use GraphQL API for efficiency

Problem: Webhook deliveries failing

Solutions:

Check webhook URL:
- Must be publicly accessible
- Use HTTPS
Verify payload:
- Check webhook secret
- Validate signature
Check recent deliveries in webhook settings

Problem: GitHub CLI authentication

Solutions:

Authenticate CLI:
```
gh auth login
```
Check token scopes:
- Ensure token has required permissions
Re-authenticate if token expired

Diagnostic Tools

Git Status Check

# Check repository status
git status
git remote -v
git log --oneline -5

# Check GitHub connection
ssh -T git@github.com
gh auth status

Network Diagnostics

# Test connectivity
ping github.com
traceroute github.com

# Check DNS
nslookup github.com

Repository Health Check

# Check for issues
gh repo view owner/repo --json issues
gh pr list --state open
gh issue list --state open

Prevention Best Practices

1. Regular Maintenance

Keep dependencies updated
Monitor security alerts
Review repository settings periodically
Clean up old branches

2. Proper Setup

Use SSH instead of HTTPS
Configure proper Git settings
Set up branch protection rules
Use issue and PR templates

3. Backup Strategy

Keep local copies of important work
Use multiple remotes if needed
Document your workflow

4. Monitoring

Set up notifications for important events
Monitor repository analytics
Review failed CI/CD runs promptly

Emergency Recovery

Lost Commits Recovery

# Find lost commits
git reflog
git checkout <commit-hash>

# Create new branch from lost commit
git checkout -b recovery-branch <commit-hash>

Repository Corruption

# Fix corrupted repository
git fsck
git gc --prune=now

# If severe, re-clone
git clone https://github.com/user/repo.git repo-new

Accidental Force Push

# Recover from force push (if you have the commits)
git push origin <old-commit>:branch-name --force

Getting Help

Community Resources

Professional Support

GitHub Enterprise support (for organizations)
Third-party Git hosting services
Professional consulting services

Quick Reference Commands

# Authentication
gh auth login                    # Authenticate GitHub CLI
ssh -T git@github.com           # Test SSH connection
git config --global user.name   # Set Git username

# Repository operations
git remote -v                   # Check remotes
git fetch upstream              # Fetch upstream changes
git rebase upstream/main        # Rebase on upstream

# Branch management
git branch -a                   # List all branches
git checkout -b new-branch      # Create new branch
git push origin --delete branch # Delete remote branch

# PR operations
gh pr create                    # Create PR
gh pr list                      # List PRs
gh pr merge                     # Merge PR

# Troubleshooting
git fsck                        # Check repository integrity
git gc --aggressive             # Clean repository
gh repo view                    # Check repository status

Remember: When in doubt, check the GitHub status page at githubstatus.com to see if there are any ongoing incidents affecting service availability.

FilesExpand file tree

GitHubTroubleshooting.md

Latest commit

History

GitHubTroubleshooting.md

File metadata and controls

GitHub Troubleshooting Guide: Common Issues & Solutions

Table of Contents

1. Authentication Issues

Problem: "Authentication failed" when pushing

Problem: "Permission denied (publickey)"

Problem: Two-factor authentication issues

2. Repository Access Problems

Problem: "Repository not found"

Problem: "You don't have permission to push to this repository"

Problem: Repository is archived or read-only

3. Git Operations Issues

Problem: "Non-fast-forward" merge conflicts

Problem: Large file upload fails

Problem: Git ignore not working

4. Pull Request Problems

Problem: PR shows merge conflicts

Problem: PR checks failing

Problem: PR automatically closed

Problem: Can't update PR branch

5. GitHub Actions Failures

Problem: Actions not running

Problem: Actions failing with permission errors

Problem: Actions running slowly

6. Branch and Merge Conflicts

Problem: Merge conflict resolution

Problem: Branch out of sync

7. Fork and Upstream Issues

Problem: Fork not syncing with upstream

Problem: Can't push to upstream

8. Security and Permissions

Problem: "Repository ruleset violation"

Problem: Dependabot failing

9. Performance Issues

Problem: Slow repository operations

Problem: GitHub Pages not updating

10. API and Integration Problems

Problem: GitHub API rate limiting

Problem: Webhook deliveries failing

Problem: GitHub CLI authentication

Diagnostic Tools

Git Status Check

Network Diagnostics

Repository Health Check

Prevention Best Practices

1. Regular Maintenance

2. Proper Setup

3. Backup Strategy

4. Monitoring

Emergency Recovery

Lost Commits Recovery

Repository Corruption

Accidental Force Push

Getting Help

Community Resources

Professional Support

Quick Reference Commands