Platform Bridge - Troubleshooting Guide¶

Solutions to common problems when usin' the platform bridge.

Platform Detection Issues¶

Problem: "Could not detect platform from git remotes"¶

Symptoms:

PlatformDetectionError: Could not detect platform from git remotes

Cause: Repository has no remotes, or remote URLs don't match GitHub/Azure DevOps patterns.

Solutions:

Check if ye have remotes:

git remote -v

If empty, add a remote:

git remote add origin https://github.com/owner/repo.git
# OR
git remote add origin https://dev.azure.com/org/project/_git/repo

Verify remote URL format:
GitHub: Must contain github.com
Azure DevOps: Must contain dev.azure.com or visualstudio.com

# GitHub format (correct)
https://github.com/owner/repo.git
git@github.com:owner/repo.git

# Azure DevOps format (correct)
https://dev.azure.com/org/project/_git/repo
https://org.visualstudio.com/project/_git/repo

Check if origin exists:

git remote show origin

If origin doesn't exist but other remotes do:

# Rename existing remote to origin
git remote rename upstream origin

Problem: "Wrong platform detected"¶

Symptoms: Bridge detects GitHub when ye have an Azure DevOps repo, or vice versa.

Cause: Multiple remotes configured, and bridge picks the wrong one.

Solution:

Check all remotes:

git remote -v

Output might show:

origin    https://github.com/mirror/repo.git (fetch)
upstream  https://dev.azure.com/real/repo/_git/main (fetch)

Fix the origin remote:

# Remove incorrect origin
git remote remove origin

# Add correct origin
git remote add origin https://dev.azure.com/real/repo/_git/main

Verify detection:

from claude.tools.platform_bridge import detect_platform, Platform

platform = detect_platform()
print(f"Detected: {platform}")
# Should now show Platform.AZDO

CLI Tool Issues¶

Problem: "GitHub CLI not found"¶

Symptoms:

CLIToolMissingError: GitHub CLI not found. Install with: brew install gh

Cause: GitHub CLI (gh) not be installed.

Solutions by Platform:

macOS:

brew install gh

Ubuntu/Debian:

sudo apt update
sudo apt install gh

Windows:

winget install GitHub.cli

Verify installation:

gh --version
# Should output: gh version 2.x.x

Problem: "Azure CLI not found"¶

Symptoms:

CLIToolMissingError: Azure CLI not found. Install with: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Cause: Azure CLI (az) not be installed.

Solutions by Platform:

macOS:

brew install azure-cli

Ubuntu/Debian:

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Windows:

winget install Microsoft.AzureCLI

Verify installation:

az --version
# Should output: azure-cli 2.x.x

Authentication Issues¶

Problem: "GitHub CLI not authenticated"¶

Symptoms:

gh: To get started with GitHub CLI, please run: gh auth login

Cause: GitHub CLI not authenticated with GitHub account.

Solution:

Run authentication:

gh auth login

Choose authentication method:
Select "GitHub.com"
Choose "HTTPS" protocol
Choose "Login with a web browser"
Follow browser prompts
Verify authentication:

gh auth status

Should show:

✓ Logged in to github.com as username

Problem: "Azure CLI not authenticated"¶

Symptoms:

Please run 'az login' to setup account.

Cause: Azure CLI not authenticated with Azure account.

Solution:

Run authentication:

az login

Follow browser prompts:
Browser opens automatically
Sign in with Azure/Microsoft account
Grant permissions
Verify authentication:

az account show

Should show account details:

{
  "name": "Your Subscription",
  "user": {
    "name": "user@domain.com"
  }
}

Problem: "Token expired"¶

Symptoms:

gh: HTTP 401: Bad credentials

or

az: Token has expired

Cause: Authentication tokens expired (GitHub OAuth tokens last ~30 days, Azure tokens last ~90 days).

Solution:

Refresh GitHub token:

gh auth refresh

Refresh Azure token:

az account get-access-token --query accessToken

If still expired:

az logout
az login

Operation Failures¶

Problem: "Branch not found"¶

Symptoms:

BranchNotFoundError: Branch 'feat/test' doesn't exist

Cause: Tryin' to create PR from branch that doesn't exist on remote.

Solution:

Check local branches:

git branch

Push branch to remote:

git push -u origin feat/test

Then create PR:

pr = bridge.create_draft_pr(
    title="Test",
    body="Body",
    source_branch="feat/test",
    target_branch="main"
)

Problem: "PR not found"¶

Symptoms:

PRNotFoundError: PR #999 doesn't exist

Cause: PR number doesn't exist in the repository.

Solution:

List all PRs:

# GitHub
gh pr list

# Azure DevOps
az repos pr list

Use correct PR number:

# Use actual PR number from list
bridge.mark_pr_ready(pr_number=123)  # Correct number

Problem: "Permission denied"¶

Symptoms:

gh: HTTP 403: Forbidden

or

az: AuthorizationFailed

Cause: Authenticated user doesn't have permission fer the operation.

Solutions:

Check repository access:
GitHub: Need write access to create issues/PRs
Azure DevOps: Need "Contribute" permission
Verify permissions:

# GitHub - Check if ye can create issue
gh issue list

# Azure DevOps - Check permissions
az repos show --repository repo-name

Request access:
Contact repository owner
Request "Write" access (GitHub) or "Contribute" (Azure DevOps)

Performance Issues¶

Problem: "CI status check takes too long"¶

Symptoms: check_ci_status() hangs or times out.

Cause: Large number of CI checks, or CI system be slow.

Solution:

Increase timeout (if needed):

# Default timeout be 60 seconds fer CI checks
# If yer CI be slower, wait longer before checkin'
import time
time.sleep(120)  # Wait 2 minutes
status = bridge.check_ci_status(pr_number=123)

Poll instead of block:

import time

def wait_for_ci(bridge, pr_number, max_wait=600):
    """Poll CI status every 30 seconds"""
    start_time = time.time()

    while time.time() - start_time < max_wait:
        status = bridge.check_ci_status(pr_number=pr_number)

        if status['pending'] == 0:
            return status  # All checks complete

        print(f"Waitin' on {status['pending']} checks...")
        time.sleep(30)

    raise TimeoutError("CI checks didn't complete in time")

Problem: "Operation times out"¶

Symptoms:

subprocess.TimeoutExpired: Command timed out after 30 seconds

Cause: Network slow, or operation takes longer than expected.

Solution:

This be controlled internally by the bridge, but if ye frequently see timeouts:

Check network connection:

ping github.com
# OR
ping dev.azure.com

Check CLI tool directly:

# GitHub - Test gh directly
time gh issue list

# Azure DevOps - Test az directly
time az repos pr list

If consistently slow:
Check VPN/proxy settings
Try different network
Contact platform support (GitHub/Azure)

Edge Cases¶

Problem: "Multiple remotes, unclear which to use"¶

Symptoms: Have both GitHub and Azure DevOps remotes, bridge picks wrong one.

Solution:

Bridge prioritizes origin, so:

# Set correct remote as origin
git remote remove origin  # Remove current origin
git remote add origin <correct-url>  # Add correct one

# Keep other remote with different name
git remote add mirror <other-url>

Problem: "Working in monorepo with multiple projects"¶

Symptoms: Monorepo has both GitHub and Azure DevOps projects.

Solution:

Create separate bridge instances fer each project:

# Project A: GitHub
bridge_a = PlatformBridge("/path/to/monorepo/project-a")

# Project B: Azure DevOps
bridge_b = PlatformBridge("/path/to/monorepo/project-b")

# Each project can have different git config

Problem: "Using SSH URLs instead of HTTPS"¶

Symptoms: Git remote uses SSH format like git@github.com:owner/repo.git

This works! Bridge handles both SSH and HTTPS URLs:

# Both formats work
git remote add origin git@github.com:owner/repo.git  # SSH
git remote add origin https://github.com/owner/repo.git  # HTTPS

Debugging¶

Enable Debug Output¶

Set environment variable fer more detailed output:

export PLATFORM_BRIDGE_DEBUG=1

Then run yer code:

from claude.tools.platform_bridge import PlatformBridge

bridge = PlatformBridge()  # Will print debug info

Debug output shows:

Detected platform
Git commands executed
CLI commands run
Subprocess output

Check CLI Tool Logs¶

GitHub CLI logs:

# See what gh commands be run
export GH_DEBUG=api

# Then run yer code

Azure CLI logs:

# Enable Azure CLI logging
az config set core.logging_enable=true

# Check logs
cat ~/.azure/logs/az.log

Getting Help¶

If ye still be havin' trouble:

Check existing issues:
GitHub Issues
Gather information:

# Platform info
uname -a

# CLI versions
gh --version
az --version

# Git info
git remote -v
git --version

Create issue with:
Problem description
Error messages (full text)
Steps to reproduce
System information (from above)

Platform Bridge - Troubleshooting Guide¶

Platform Detection Issues¶

Problem: "Could not detect platform from git remotes"¶

Problem: "Wrong platform detected"¶

CLI Tool Issues¶

Problem: "GitHub CLI not found"¶

Problem: "Azure CLI not found"¶

Authentication Issues¶

Problem: "GitHub CLI not authenticated"¶

Problem: "Azure CLI not authenticated"¶

Problem: "Token expired"¶

Operation Failures¶

Problem: "Branch not found"¶

Problem: "PR not found"¶

Problem: "Permission denied"¶

Performance Issues¶

Problem: "CI status check takes too long"¶

Problem: "Operation times out"¶

Edge Cases¶

Problem: "Multiple remotes, unclear which to use"¶

Problem: "Working in monorepo with multiple projects"¶

Problem: "Using SSH URLs instead of HTTPS"¶

Debugging¶

Enable Debug Output¶

Check CLI Tool Logs¶

Getting Help¶

See Also¶