Error Reference
Complete reference of all error messages in Broski with causes and solutions.
How to Use This Reference
- • Search the page: Use Ctrl+F (or Cmd+F on Mac) to search for the exact error text
- • Browse by category: Errors are organized by component
- • Check the quick reference: Jump to common errors at a glance
Quick Reference
| Error/Code | Component | Quick Fix |
|---|---|---|
| Old Broski QR | Pairing | Update broski on your Mac, then run broski-link pair |
| Port in use | Bridge | kill <PID> or --port 0 |
| Claude Code auth missing | Claude Code | export ANTHROPIC_API_KEY=... or claude login |
| Offline or Asleep | Link | Wake the Mac; check broski-link status |
| Pairing QR expired | Pairing | Run broski-link pair and scan the new code |
| Access denied | Files | Use paths under ~ or /tmp |
| Rate limited (429) | API | Wait 1 minute, retry |
| OAuth token expired | Auth | claude login |
| Scan timeout | File Search | Informational, cached results used |
Bridge Startup Errors
Source: Bridge startup
Cause: Another process (often a previous broski instance) is using the port. This commonly happens when a previous bridge was suspended with Ctrl+Z instead of Ctrl+C.
# Find the process using the port
lsof -nP -iTCP:18274 -sTCP:LISTEN
# Kill it
kill <PID>
# Or use random port
broski --port 0Connection Errors
Source: Pairing
Cause: None of the addresses in the QR answered within 1.5 seconds. The Mac may be asleep, broski-link may not be running, or the phone is on a different network.
broski status
broski-link statusSource: Pairing
Cause: The QR carries neither a local address nor a relay. Your Mac has no reachable network address and no relay configured.
Solution: Connect the Mac to a network, or configure a relay in ~/.broski/link/config.json, then run broski-link pair.
Source: Pairing
Solution: Check broski-link status, then run broski-link pair and try again.
Source: Pairing
Cause: The pairing secret was wrong or already used, or the QR was replaced by a newer one.
Solution: Run broski-link pair once and scan that code.
Cause: The Mac is asleep, off, or cannot reach the relay and the phone cannot reach it directly.
# On the Mac
broski-link status
broski logs --followPairing Errors
Source: Pairing QR check
Cause: A pairing QR works for 10 minutes and only once.
broski-link pairSource: Scan screen
Cause: The QR was made by a version of broski from before Broski Link.
broski update
broski install
broski-link pairSource: Scan screen
Cause: The scanned code is not a broski://pair link.
Solution: Scan the code that broski-link pair prints.
Source: Pairing
Cause: The address in the QR answered, but the machine's fingerprint does not match the one in the QR. This protects you from pairing with the wrong machine.
Solution: Run broski-link pair on the machine you want and scan that code.
Cause: A machine pairs with at most 32 devices.
broski-link devices
broski-link revoke <device id prefix>Claude Code Errors
Source: Claude Code initialization
Cause: No valid Anthropic authentication found.
# Option 1: Set API Key
export ANTHROPIC_API_KEY=sk-ant-...
broski
# Option 2: Login via Claude CLI
claude loginSource: Claude Code streaming
Cause: General error during Claude Code execution. Check the accompanying message for details.
- Rate limiting: Wait and retry
- Context too long: Start a new session
- Network issues: Check internet connection
Source: Claude Code permission handling
Cause: User rejected a tool permission request in the app.
Note: This is intentional user action. If you want to allow the action, tap "Allow" instead of "Deny".
Relay Errors
Source: broski-link status
Cause: The relay URL in ~/.broski/link/config.json is wrong or unreachable, or no relay is configured.
# Check the relay state
broski-link status
# Fix the URL, then restart
broski restartPTY (Terminal) Errors
The bridge's native terminal helper could not start a session. Verify the project path exists and restart the bridge.
The requested PTY session ID doesn't exist (may have been deleted). Refresh the terminal list or create a new session.
File Access Errors
Source: File operations
Cause: Requested file path is outside allowed directories. For security, Broski only allows access to:
- Home directory (~)
- /tmp
- /var/tmp
The requested file doesn't exist at the specified path. Verify the path is correct and file permissions.
File exceeds size limit (default 10MB for binary files). Use terminal commands for large files instead.
HTTP Status Codes
Client Errors (4xx)
| Code | Meaning | Solution |
|---|---|---|
| 400 | Bad Request | Check request format and required parameters |
| 401 | Unauthorized | The local bearer token was missing or wrong (agent hooks and the dashboard use it). Restart the bridge to reload it |
| 403 | Forbidden | Check permissions and path restrictions |
| 404 | Not Found | Verify resource ID or path is correct |
| 429 | Too Many Requests | Wait for rate limit to reset (usually 1 minute) |
Server Errors (5xx)
| Code | Meaning | Solution |
|---|---|---|
| 500 | Internal Server Error | Check bridge logs, restart bridge |
| 502 | Bad Gateway | Backend (Claude Code/Pi) unavailable, restart bridge |
| 503 | Service Unavailable | Wait and retry, or restart bridge |
Plugin Errors
Failed to read plugins from ~/.claude/plugins/. Check directory permissions or remove corrupted plugin directories.
Could not write to ~/.broski/plugins-config.json. Check disk space and directory permissions.
Custom Tools Errors
A custom HTTP tool failed. Check that target URL is reachable, authentication headers are correct, and API endpoint is operational.
A custom script tool failed. Verify script path exists, is executable, and test manually:
/path/to/your/script argsCustom tool has unrecognized handler type. Must be http, script, or builtin.
Custom tool definition failed validation. Check for required fields (name, description, command), valid parameter types, and correct JSON schema format.
File Search Errors
Path is outside allowed directories. File search only works in home directory (~), /tmp, and /var/tmp.
Project path doesn't exist or isn't a directory. Verify you're providing a directory, not a file path.
Attempted to search from filesystem root (/), which is too broad. Specify a more specific project directory.
Project has too many files. Partial results returned. Add patterns to .gitignore to exclude large directories.
Getting Help
- Run
broski logs --followwhile reproducing the issue - Run
broski doctor --profile pairing(or network/agents/daemon) - Export a support bundle:
broski logs --export - Check the troubleshooting guide
- Contact support at broskiappp@gmail.com