Troubleshooting¶

Common issues and their solutions.

Installation Issues¶

Binary Not Found¶

Symptom: command not found: remote-juggler

Solution:

Check installation directory:
```
ls ~/.local/bin/remote-juggler
```

Add to PATH:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

Or use full path:
```
~/.local/bin/remote-juggler status
```

Permission Denied¶

Symptom: Permission denied when running

Solution:

chmod +x ~/.local/bin/remote-juggler

macOS Gatekeeper Block¶

Symptom: "remote-juggler cannot be opened because it is from an unidentified developer"

Solution:

xattr -d com.apple.quarantine ~/.local/bin/remote-juggler

Or: System Preferences > Security & Privacy > Allow

Configuration Issues¶

No Identities Found¶

Symptom: remote-juggler list shows no identities

Solution:

Import from SSH config:
```
remote-juggler config import
```

Or create config manually:

remote-juggler config init
# Edit ~/.config/remote-juggler/config.json

Config File Not Found¶

Symptom: Configuration warnings

Solution:

# Initialize configuration
remote-juggler config init

# Verify location
remote-juggler config show

JSON Parse Error¶

Symptom: Failed to parse config file

Solution:

Validate JSON:

cat ~/.config/remote-juggler/config.json | python -m json.tool

Fix syntax errors (missing commas, quotes, braces)

Reset to default:

rm ~/.config/remote-juggler/config.json
remote-juggler config init

SSH Issues¶

Permission Denied (publickey)¶

Symptom: SSH connection fails with "Permission denied"

Diagnosis:

# Test SSH connection with verbose output
ssh -vT git@gitlab-work

Solutions:

Check key exists:
```
ls -la ~/.ssh/id_ed25519_work*
```

Check key permissions:

chmod 600 ~/.ssh/id_ed25519_work
chmod 644 ~/.ssh/id_ed25519_work.pub

Add to SSH agent:
```
ssh-add ~/.ssh/id_ed25519_work
```
Verify key is registered with provider

Could Not Resolve Hostname¶

Symptom: ssh: Could not resolve hostname gitlab-work

Solution:

Check SSH config:

grep -A5 "Host gitlab-work" ~/.ssh/config

Ensure Host entry exists and is valid.

Wrong Identity Used¶

Symptom: Commits show wrong email

Diagnosis:

remote-juggler status
git config user.email

Solution:

Verify current identity:
```
remote-juggler status
```
Switch to correct identity:
```
remote-juggler switch work
```

Verify SSH config has IdentitiesOnly yes:

Host gitlab-work
    IdentitiesOnly yes

Keychain Issues¶

Token Not Found¶

Symptom: No token found for identity

Solution:

Store token:

remote-juggler token set work
# Enter token when prompted

Verify storage:

security find-generic-password -s "remote-juggler.gitlab.work" -w

Keychain Access Denied¶

Symptom: System prompts for Keychain access repeatedly

Solution:

Click "Always Allow" when prompted
Check Keychain Access app for any blocked items

Reset Keychain permissions:

security unlock-keychain ~/Library/Keychains/login.keychain-db

Not macOS¶

Symptom: Keychain integration requires macOS

Solution:

Use environment variables instead:

export GITLAB_WORK_TOKEN="glpat-..."

Or use provider CLI authentication:

glab auth login

GPG Issues¶

Failed to Sign Data¶

Symptom: error: gpg failed to sign the data

Diagnosis:

# Test GPG signing
echo "test" | gpg --clearsign

Solutions:

Set GPG TTY:
```
export GPG_TTY=$(tty)
```
Restart GPG agent:
```
gpgconf --kill gpg-agent
```

Install pinentry-mac (macOS):

brew install pinentry-mac
echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

Secret Key Not Available¶

Symptom: gpg: signing failed: secret key not available

Solution:

List available keys:
```
gpg --list-secret-keys
```
Verify key ID in config matches:
```
remote-juggler gpg status
```
Import key if needed:
```
gpg --import private-key.asc
```

Provider CLI Issues¶

glab Not Authenticated¶

Symptom: glab not authenticated

Solution:

# Authenticate with token
glab auth login -h gitlab.com

# Or with browser
glab auth login -h gitlab.com --web

gh Not Found¶

Symptom: gh not installed

Solution:

# macOS
brew install gh

# Or download from https://cli.github.com

MCP/ACP Issues¶

Server Not Responding¶

Symptom: AI assistant can't connect to RemoteJuggler

Diagnosis:

# Test MCP server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}' | \
  remote-juggler --mode=mcp

Solutions:

Check binary path in configuration:

{
  "command": "/full/path/to/remote-juggler"
}

Check permissions:
```
chmod +x ~/.local/bin/remote-juggler
```

Enable debug logging:

REMOTE_JUGGLER_VERBOSE=1 remote-juggler --mode=mcp 2>debug.log

No Tools Available¶

Symptom: AI assistant sees no tools

Solution:

Test tools/list:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | remote-juggler --mode=mcp

Verify MCP configuration:

{
  "mcpServers": {
    "remote-juggler": {
      "command": "remote-juggler",
      "args": ["--mode=mcp"]
    }
  }
}

Getting Help¶

Debug Output¶

Enable verbose logging:

remote-juggler --verbose <command>

Version Information¶

remote-juggler --version

Report Issues¶

File issues at: https://gitlab.com/tinyland/projects/remote-juggler/-/issues

Include: - RemoteJuggler version - OS and version - Command that failed - Error message - Debug output (with secrets redacted)