Troubleshooting

Troubleshooting Guide

This guide covers common issues you might encounter when using githubauthlib and their solutions.

Common Issues

Token Not Found

Symptoms

• TokenNotFoundError is raised
• "GitHub access token not found" error message

Possible Causes

1. Git credentials not configured
2. Token not stored in system keychain
3. Token stored with incorrect protocol/host

Solutions

1. Verify Git credentials are configured:

# Check Git configuration
git config --global credential.helper

# macOS
git config --global credential.helper osxkeychain

# Windows
git config --global credential.helper manager

# Linux
git config --global credential.helper libsecret

2. Store credentials manually:

# This will prompt for your credentials
git credential-osxkeychain store
protocol=https
host=github.com
username=your-username
password=ghp_your_token

Permission Denied

Symptoms

• CredentialHelperError is raised
• "Permission denied" or similar error message

Possible Causes

1. Insufficient permissions for keychain access
2. System keychain locked
3. Application not trusted by system

Solutions

macOS

1. Open Keychain Access
2. Find the GitHub entry
3. Update permissions for the credential

Windows

1. Open Credential Manager
2. Check Generic Credentials
3. Verify GitHub credentials exist

Linux

1. Check libsecret installation:

which secret-tool

2. Test libsecret access:

secret-tool lookup host github.com

Unsupported Platform

Symptoms

• PlatformNotSupportedError is raised
• "Unsupported operating system" message

Solutions

1. Verify your operating system is supported:

   • macOS
   • Windows
   • Linux

2. Check platform-specific dependencies:

# Linux
sudo apt-get install libsecret-tools  # Ubuntu/Debian
sudo dnf install libsecret            # Fedora
sudo pacman -S libsecret             # Arch Linux

Invalid Token Format

Symptoms

• InvalidTokenError is raised
• "Invalid token format" error message

Solutions

1. Verify token format:

   • Personal tokens: ghp_ prefix followed by 36+ characters
   • Organization tokens: gho_ prefix followed by 36+ characters
   • Fine-grained tokens: github_pat_ prefix followed by 60+ characters

2. Generate a new token:

   • Go to GitHub Settings > Developer settings > Personal access tokens
   • Generate new token
   • Store token securely

Import Errors

Symptoms

• ModuleNotFoundError
• ImportError

Solutions

1. Verify installation:

pip list | grep githubauthlib

2. Reinstall package:

pip uninstall githubauthlib
pip install githubauthlib

3. Check Python version:

python --version  # Should be 3.9 or higher

Logging Issues

Symptoms

• No log output
• Insufficient log information

Solutions

1. Configure logging:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

2. Enable debug logging for the library:

logging.getLogger('githubauthlib').setLevel(logging.DEBUG)

Debugging Steps

1. Check Environment

# Python version
python --version

# Installed packages
pip freeze

# Operating system
python -c "import platform; print(platform.system())"

2. Test Git Configuration

# Check Git version
git --version

# List Git configuration
git config --list

# Test Git credential helper
git credential fill <<EOF
protocol=https
host=github.com
EOF

3. Test System Keychain

macOS

security find-generic-password -s github.com

Windows

cmdkey /list | findstr github.com

Linux

secret-tool search host github.com

Getting More Help

If you're still experiencing issues:

1. Enable debug logging and collect logs
2. Check the GitHub Issues
3. Create a new issue with:
   • Operating system and version
   • Python version
   • Installation method
   • Error messages
   • Steps to reproduce
   • Debug logs (with sensitive information removed)

Common Error Messages

CredentialHelperError

try:
    token = get_github_token()
except CredentialHelperError as e:
    if "not found" in str(e):
        print("Credential helper not configured")
    elif "permission denied" in str(e):
        print("Permission issues with credential helper")
    else:
        print(f"Unknown credential helper error: {e}")

PlatformNotSupportedError

try:
    token = get_github_token()
except PlatformNotSupportedError as e:
    print(f"System not supported: {platform.system()}")

InvalidTokenError

try:
    token = get_github_token()
except InvalidTokenError as e:
    print("Token format is invalid")
    print("Supported formats: ghp_, gho_, github_pat_")

TokenNotFoundError

try:
    token = get_github_token()
except TokenNotFoundError as e:
    print("No token found in system keychain")
    print("Configure Git credentials first")

Performance Issues

Slow Token Retrieval

Symptoms

• Token retrieval takes more than 1 second
• System appears to hang

Solutions

1. Cache the token:

from functools import lru_cache

@lru_cache(maxsize=1)
def get_cached_token():
    return get_github_token()

2. Check system keychain performance:
   • Remove unused credentials
   • Update system keychain software
   • Check system resources

Security Best Practices

1. Never log tokens
2. Use environment variables when needed
3. Rotate tokens regularly
4. Use fine-grained tokens
5. Set appropriate token permissions

Reporting Security Issues

For security-related issues:

1. DO NOT create a public issue
2. Email [email protected]
3. Include detailed information
4. Follow responsible disclosure