Common Issues and Solutions¶

This guide covers the most common issues users encounter with GitBridge and their solutions.

Quick Diagnostics¶

Before troubleshooting, run the diagnostic command:

1

gitbridge diagnose --verbose

This will check: - ✓ Python version and dependencies - ✓ Network connectivity - ✓ GitHub API access - ✓ Proxy configuration - ✓ SSL certificates - ✓ Browser availability (if using browser method)

Authentication Issues¶

Error: 401 Unauthorized¶

1
2

Error: Authentication failed (401 Unauthorized)
Please check your GitHub token

Causes: - Invalid or expired GitHub token - Token lacks required permissions - Token not properly configured

Solutions:

1. Verify token is valid:

   Bash
   1 2	# Test token directly curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

2. Check token permissions:

3. Go to GitHub → Settings → Developer settings → Personal access tokens
4. Ensure token has repo scope for private repositories

5. For public repos, public_repo scope is sufficient

6. Set token correctly:

   Bash
   1 2 3 4 5 6 7 8 9 10	# Environment variable (recommended) export GITHUB_TOKEN=ghp_YourTokenHere gitbridge sync --config config.yaml # Command line gitbridge sync --token ghp_YourTokenHere --repo URL --local PATH # Config file echo "auth: token: ghp_YourTokenHere" >> config.yaml

Error: 403 Forbidden¶

1

Error: API rate limit exceeded (403 Forbidden)

Solutions:

1. Check rate limit status:

   Bash
   1 2	curl -H "Authorization: token YOUR_TOKEN" \ https://api.github.com/rate_limit

2. Wait for rate limit reset:

   Python
   1 2	# The error message will show when limit resets # Typically 1 hour from when limit was hit

3. Use authentication to increase limits:

4. Unauthenticated: 60 requests/hour

5. Authenticated: 5,000 requests/hour

6. Switch to browser method temporarily:

   Bash
   1	gitbridge sync --method browser --config config.yaml

Network and Connectivity Issues¶

Error: Connection Timeout¶

1
2

ConnectTimeout: HTTPSConnectionPool(host='api.github.com', port=443): 
Max retries exceeded with url: /repos/user/repo

Causes: - Firewall blocking GitHub API - Proxy configuration required - Network connectivity issues

Solutions:

1. Test basic connectivity:

   Bash
   1 2 3 4 5	# Test GitHub API curl https://api.github.com # Test with proxy curl --proxy http://proxy:8080 https://api.github.com

2. Configure proxy:

   Bash
   1 2 3 4 5 6	# Auto-detect gitbridge sync --auto-proxy --config config.yaml # Manual proxy export HTTPS_PROXY=http://proxy.company.com:8080 gitbridge sync --config config.yaml

3. Try browser method:

   Bash
   1	gitbridge sync --method browser --config config.yaml

Error: Proxy Authentication Required¶

1

ProxyError: 407 Proxy Authentication Required

Solutions:

1. Provide proxy credentials:

   Bash
   1 2 3 4 5	# Windows domain authentication export HTTPS_PROXY=http://DOMAIN\\username:password@proxy:8080 # Regular authentication export HTTPS_PROXY=http://username:password@proxy:8080

2. Use configuration file:

   YAML
   1 2 3 4 5 6	network: proxy: https: http://proxy.company.com:8080 auth: username: your_username password: your_password

SSL/Certificate Issues¶

Error: SSL Certificate Verification Failed¶

1
2

SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: 
self signed certificate in certificate chain

Causes: - Corporate proxy with custom certificates - Self-signed certificates - Missing root CA certificates

Solutions:

1. Auto-detect certificates:

   Bash
   1 2	# Windows: Extract from certificate store gitbridge sync --auto-cert --config config.yaml

2. Use custom certificate bundle:

   Bash
   1 2 3 4 5	# Get company certificates from IT gitbridge sync --ca-bundle /path/to/company-ca-bundle.crt # Or set environment variable export REQUESTS_CA_BUNDLE=/path/to/company-ca-bundle.crt

3. Combine certificates:

   Bash
   1 2 3	# Combine company and default certificates cat /etc/ssl/company-ca.crt $(python -m certifi) > combined.crt export REQUESTS_CA_BUNDLE=combined.crt

4. Last resort - disable verification:

   Bash
   1 2	# WARNING: Insecure! Only for testing! gitbridge sync --no-ssl-verify --config config.yaml

Browser Method Issues¶

Error: Chrome/Chromium Not Found¶

1

WebDriverException: Message: 'chromedriver' executable needs to be in PATH

Solutions:

1. Install Chrome/Chromium:

   Bash
   1 2 3 4 5 6 7 8	# Windows winget install Google.Chrome # macOS brew install --cask google-chrome # Linux sudo apt-get install chromium-browser

2. Specify browser path:

   Bash
   1 2 3	gitbridge sync --method browser \ --browser-path "/usr/bin/chromium" \ --config config.yaml

3. Check ChromeDriver:

   Bash
   1 2 3	# Selenium 4+ manages ChromeDriver automatically # For manual installation: pip install webdriver-manager

Error: Browser Timeout¶

1

TimeoutException: Message: timeout: Timed out receiving message from renderer

Solutions:

1. Increase timeout:

   Bash
   1 2 3	gitbridge sync --method browser \ --browser-timeout 60 \ --config config.yaml

2. Run in non-headless mode for debugging:

   Bash
   1	gitbridge sync --method browser --no-headless

3. Check memory usage:

   Bash
   1 2 3	# Browser method uses more memory # Ensure sufficient RAM available free -h # Linux

File System Issues¶

Error: Permission Denied¶

1

PermissionError: [Errno 13] Permission denied: '/path/to/file'

Solutions:

1. Check directory permissions:

   Bash
   1 2 3 4 5	# Check permissions ls -la /path/to/directory # Fix permissions chmod -R u+w /path/to/directory

2. Use different directory:

   Bash
   1	gitbridge sync --local ~/writable-directory --repo URL

3. Run as appropriate user:

   Bash
   1 2	# Avoid running as root # Use your normal user account

Error: Disk Space¶

1

OSError: [Errno 28] No space left on device

Solutions:

1. Check available space:

   Bash
   1	df -h /path/to/directory

2. Clean up old files:

   Bash
   1 2 3 4 5	# Remove .gitbridge cache rm -rf /path/to/repo/.gitbridge # Full resync after cleanup gitbridge sync --force --config config.yaml

Configuration Issues¶

Error: Invalid Configuration¶

1

ConfigError: Invalid configuration file: config.yaml

Solutions:

1. Validate YAML syntax:

   Bash
   1 2 3 4	# Online validator: https://www.yamllint.com/ # Or use Python python -c "import yaml; yaml.safe_load(open('config.yaml'))"

2. Check required fields:

   YAML
   1 2 3 4 5 6	# Minimum required configuration repository: url: https://github.com/user/repo local: path: /path/to/local

3. Use example configuration:

   Bash
   1 2	cp config.example.yaml config.yaml # Edit config.yaml with your settings

Error: Environment Variable Not Found¶

1

ConfigError: Environment variable GITHUB_TOKEN not found

Solutions:

1. Set environment variable:

   Bash
   1 2 3 4 5 6 7 8	# Linux/macOS export GITHUB_TOKEN=ghp_YourToken # Windows Command Prompt set GITHUB_TOKEN=ghp_YourToken # Windows PowerShell $env:GITHUB_TOKEN="ghp_YourToken"

2. Use .env file:

   Bash
   1 2	echo "GITHUB_TOKEN=ghp_YourToken" > .env # GitBridge will load .env automatically

Performance Issues¶

Slow Synchronization¶

Symptoms: - Initial sync takes hours - Incremental updates are slow - High memory usage

Solutions:

1. Use API method (faster):

   Bash
   1	gitbridge sync --method api --config config.yaml

2. Enable parallel downloads:

   YAML
   1 2 3	sync: parallel_downloads: 10 chunk_size: 2097152 # 2MB chunks

3. Skip large files:

   YAML
   1 2 3	sync: skip_large_files: true large_file_size: 104857600 # 100MB

4. Use incremental mode:

   Bash
   1 2	# Default behavior, but ensure it's enabled gitbridge sync --incremental --config config.yaml

Repository-Specific Issues¶

Error: Repository Not Found¶

1

HTTPError: 404 Client Error: Not Found for url: https://api.github.com/repos/user/repo

Solutions:

1. Check repository URL:

   Bash
   1 2 3 4 5 6	# Correct format https://github.com/owner/repository # Not https://github.com/owner/repository.git https://github.com/owner/repository/tree/main

2. Check repository visibility:

3. Private repos require authentication

4. Check if repo exists and you have access

5. Check for typos:

   Bash
   1 2	# Test in browser first open https://github.com/owner/repository

Error: Invalid Reference¶

1

GitBridgeError: Reference 'feature/branch' not found in repository

Solutions:

1. List available branches:

   Bash
   1 2 3	# Using API curl -H "Authorization: token YOUR_TOKEN" \ https://api.github.com/repos/owner/repo/branches

2. Use correct reference:

   Bash
   1 2 3 4 5 6 7 8	# Branch gitbridge sync --ref main # Tag gitbridge sync --ref v1.0.0 # Commit SHA gitbridge sync --ref abc123def

Debug Mode¶

For persistent issues, enable debug mode:

1
2
3
4
5
6
7

# Maximum verbosity
gitbridge sync --config config.yaml \
  --verbose \
  --log-file debug.log

# Check log file
tail -f debug.log

Getting Help¶

If these solutions don't resolve your issue:

1. Run diagnostics:

   Bash
   1	gitbridge diagnose --verbose > diagnostic.txt

2. Collect information:

3. GitBridge version: gitbridge --version
4. Python version: python --version
5. Operating system: uname -a (Linux/macOS) or ver (Windows)
6. Full error message and stack trace

7. Configuration file (remove sensitive data)

8. Create issue:

9. Visit: https://github.com/nevedomski/gitbridge/issues/new
10. Include diagnostic information
11. Describe steps to reproduce

Prevention Tips¶

1. Test configuration early:

   Bash
   1	gitbridge status --config config.yaml

2. Use verbose mode during setup:

   Bash
   1	gitbridge sync --verbose --dry-run

3. Keep credentials secure:

4. Use environment variables for tokens

5. Never commit tokens to version control

6. Monitor rate limits:

   Bash
   1	gitbridge status --show-limits

7. Regular updates:

   Bash
   1	pip install --upgrade gitbridge