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/CodeComponentQuick Fix
Old Broski QRPairingUpdate broski on your Mac, then run broski-link pair
Port in useBridgekill <PID> or --port 0
Claude Code auth missingClaude Codeexport ANTHROPIC_API_KEY=... or claude login
Offline or AsleepLinkWake the Mac; check broski-link status
Pairing QR expiredPairingRun broski-link pair and scan the new code
Access deniedFilesUse paths under ~ or /tmp
Rate limited (429)APIWait 1 minute, retry
OAuth token expiredAuthclaude login
Scan timeoutFile SearchInformational, cached results used

Bridge Startup Errors

"Bridge port {port} is already in use"

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.

bash
# Find the process using the port
lsof -nP -iTCP:18274 -sTCP:LISTEN

# Kill it
kill <PID>

# Or use random port
broski --port 0

Connection Errors

"The machine did not answer. Check that it is running and that this phone can reach it."

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.

bash
broski status
broski-link status
"This QR code has no address to reach the machine at."

Source: 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.

"The machine did not confirm the pairing in time."

Source: Pairing

Solution: Check broski-link status, then run broski-link pair and try again.

"The machine closed the connection before confirming the pairing."

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.

Machine shows as Asleep or Offline

Cause: The Mac is asleep, off, or cannot reach the relay and the phone cannot reach it directly.

bash
# On the Mac
broski-link status
broski logs --follow

Pairing Errors

"the pairing QR expired at ..."

Source: Pairing QR check

Cause: A pairing QR works for 10 minutes and only once.

bash
broski-link pair
"This is an old Broski QR — update broski on your Mac and scan the new code."

Source: Scan screen

Cause: The QR was made by a version of broski from before Broski Link.

bash
broski update
broski install
broski-link pair
"This QR code is not a Broski pairing code."

Source: Scan screen

Cause: The scanned code is not a broski://pair link.

Solution: Scan the code that broski-link pair prints.

"That machine is not the one this QR code pairs with."

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.

Pairing refused

Cause: A machine pairs with at most 32 devices.

bash
broski-link devices
broski-link revoke <device id prefix>

Claude Code Errors

"Claude Code auth not configured" / "cc_auth_missing"

Source: Claude Code initialization

Cause: No valid Anthropic authentication found.

bash
# Option 1: Set API Key
export ANTHROPIC_API_KEY=sk-ant-...
broski

# Option 2: Login via Claude CLI
claude login
"cc_error"

Source: 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
"User denied permission"

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

Relay not connected

Source: broski-link status

Cause: The relay URL in ~/.broski/link/config.json is wrong or unreachable, or no relay is configured.

bash
# Check the relay state
broski-link status

# Fix the URL, then restart
broski restart

PTY (Terminal) Errors

"Failed to create PTY session"

The bridge's native terminal helper could not start a session. Verify the project path exists and restart the bridge.

"PTY session not found"

The requested PTY session ID doesn't exist (may have been deleted). Refresh the terminal list or create a new session.

File Access Errors

"Access denied"

Source: File operations

Cause: Requested file path is outside allowed directories. For security, Broski only allows access to:

  • Home directory (~)
  • /tmp
  • /var/tmp
"File not found"

The requested file doesn't exist at the specified path. Verify the path is correct and file permissions.

"File too large"

File exceeds size limit (default 10MB for binary files). Use terminal commands for large files instead.

HTTP Status Codes

Client Errors (4xx)

CodeMeaningSolution
400Bad RequestCheck request format and required parameters
401UnauthorizedThe local bearer token was missing or wrong (agent hooks and the dashboard use it). Restart the bridge to reload it
403ForbiddenCheck permissions and path restrictions
404Not FoundVerify resource ID or path is correct
429Too Many RequestsWait for rate limit to reset (usually 1 minute)

Server Errors (5xx)

CodeMeaningSolution
500Internal Server ErrorCheck bridge logs, restart bridge
502Bad GatewayBackend (Claude Code/Pi) unavailable, restart bridge
503Service UnavailableWait and retry, or restart bridge

Plugin Errors

"Error scanning plugins directory"

Failed to read plugins from ~/.claude/plugins/. Check directory permissions or remove corrupted plugin directories.

"Failed to save plugin config"

Could not write to ~/.broski/plugins-config.json. Check disk space and directory permissions.

Custom Tools Errors

"Error executing HTTP tool"

A custom HTTP tool failed. Check that target URL is reachable, authentication headers are correct, and API endpoint is operational.

"Error executing script"

A custom script tool failed. Verify script path exists, is executable, and test manually:

bash
/path/to/your/script args
"Unknown handler type"

Custom tool has unrecognized handler type. Must be http, script, or builtin.

"Invalid tool: {errors}"

Custom tool definition failed validation. Check for required fields (name, description, command), valid parameter types, and correct JSON schema format.

File Search Errors

"Access denied or invalid path"

Path is outside allowed directories. File search only works in home directory (~), /tmp, and /var/tmp.

"Not a directory" / "Directory not found"

Project path doesn't exist or isn't a directory. Verify you're providing a directory, not a file path.

"Refusing to scan filesystem root"

Attempted to search from filesystem root (/), which is too broad. Specify a more specific project directory.

"Scan timeout after 5000ms"

Project has too many files. Partial results returned. Add patterns to .gitignore to exclude large directories.

Getting Help

If you can't find your error
  1. Run broski logs --follow while reproducing the issue
  2. Run broski doctor --profile pairing (or network/agents/daemon)
  3. Export a support bundle: broski logs --export
  4. Check the troubleshooting guide
  5. Contact support at broskiappp@gmail.com

Related