Error Reference

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 0

Source: OpenCode bootstrap

Cause: OpenCode is not installed or not in PATH.

# Verify installation
which opencode && opencode --version

# Install if missing
bun add -g opencode-ai

Source: OpenCode health check

Cause: OpenCode process started but HTTP server didn't respond within 10 seconds.

# Try running OpenCode manually to see errors
opencode serve

# Try manual mode
broski --manual --opencode-url http://localhost:4096

Source: Attach mode

Cause: You used --attach but no running OpenCode instances were detected.

# Start OpenCode manually first
opencode serve

# Or use managed mode (default)
broski

Source: CLI validation

Cause: You specified --manual without providing the OpenCode server URL.

broski --manual --opencode-url http://localhost:4096

# Or via environment variable
OPENCODE_BASE_URL=http://localhost:4096 broski --manual

Source: WebSocket authentication

Cause: Invalid or missing auth token. QR code may be outdated or token was regenerated.

Solution: Re-scan the QR code from the bridge terminal.

Source: WebSocket connection

Cause: HTTP-to-WebSocket upgrade was rejected. Server may be overloaded or proxy interfering.

Solution: Verify bridge is running, check no proxy is modifying WebSocket headers, restart bridge.

Source: WebSocket health monitoring

Cause: Server didn't receive a pong response within 90 seconds. Network may have dropped silently or app was backgrounded.

Solution: App will auto-reconnect. Check network connectivity on both devices.

Source: WebSocket client

Cause: Connection attempt didn't complete within 5 seconds. Bridge may not be running, wrong IP/port, or firewall blocking.

# Verify bridge is running
curl http://<ip>:18274/

# Check firewall settings
# Verify same network (for local)

Source: WebSocket service

Cause: Empty or malformed connection URI received.

Solution: Re-scan the QR code from the bridge terminal.

Source: Connection provider

Cause: App tried all available endpoints (local IP, Tailscale IP, MagicDNS) but none succeeded.

# Verify bridge is running
broski doctor

# Check firewall settings
# For local: ensure same WiFi
# For Tailscale: ensure both devices connected

Source: Token validation

Cause: Provided token doesn't match bridge's expected token.

Solution: Re-scan QR code. If you regenerated the token, scan the new QR code.

Source: Token validation

Cause: No authentication token was provided in the connection request.

# Token should be in URL:
wss://<ip>:18274?token=<your-token>

Source: Token storage

Cause: Couldn't save token to ~/.broski/token.json. QR codes may rotate between restarts.

# Check permissions
ls -la ~/.broski/

# Create directory if needed
mkdir -p ~/.broski
chmod 700 ~/.broski

Source: Doctor check

Cause: OpenCode is not installed or not in your PATH.

# Install OpenCode
bun add -g opencode-ai

# Reload shell
source ~/.bashrc  # or ~/.zshrc

Source: Health check

Cause: OpenCode process is running but not responding to HTTP requests.

# Restart bridge (it will restart OpenCode)
# Press Ctrl+C, then:
broski

# Or test OpenCode directly
opencode serve

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 login

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

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".

Source: Doctor check

Cause: Tailscale app is not found on your system.

# Run the setup wizard
broski setup-tailscale

# Or install manually
brew install --cask tailscale  # macOS

Source: Tailscale check

Cause: Tailscale is installed but not connected to your tailnet.

# Check status
tailscale status

# Connect
tailscale up

Source: Funnel setup

Cause: You tried to use --funnel but Funnel is not enabled in the Tailscale admin console.

1. Go to admin.tailscale.com
2. Navigate to Access controls
3. Enable Funnel for your device
4. Wait a few minutes, then retry

Source: Funnel setup

Cause: The tailscale funnel command failed.

# Verify Tailscale is connected
tailscale status

# Check Funnel is enabled in admin console
# Try without Funnel first
broski

Failed to list terminal sessions from OpenCode. Verify OpenCode is running and restart the bridge.

OpenCode failed to create a new terminal session. Check OpenCode logs and verify the project path exists.

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

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.

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.

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 args

Custom 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.

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.