AI Backend Issues

Troubleshoot issues specific to OpenCode, Claude Code, Codex, and Pi backends.

OpenCode Issues

"OpenCode not found" / "OpenCode not starting"

Bridge can't find or start OpenCode.

bash

# Check if OpenCode is installed
which opencode && opencode --version

# If not found, install it
curl -fsSL https://opencode.ai/install | bash
# or: bun add -g opencode-ai

# Then reload your shell
source ~/.bashrc  # or ~/.zshrc

"OpenCode started but did not become ready"

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

bash

# Try running OpenCode manually to see errors
opencode serve

# Check if port is in use
lsof -i :4096

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

Provider Errors / "Provider not configured"

OpenCode needs an AI provider configured (Anthropic, OpenAI, etc).

bash

# Check if API key is set
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

# Set API key (add to ~/.bashrc or ~/.zshrc for persistence)
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# Check OpenCode config
cat ~/.config/opencode/opencode.jsonc

OpenCode Crashes / Health Check Failures

Bridge shows "OpenCode not running", sessions disappear.

The bridge auto-restarts managed OpenCode if it crashes
Check system resources (RAM, CPU)
Look for error messages in bridge logs

bash

# Run backend-focused diagnostics
broski doctor --profile agents

# Check OpenCode process
ps aux | grep opencode

# Test OpenCode health directly
curl http://localhost:4096/path

# Follow logs while reproducing issue
broski logs --follow

Common Mistakes - OpenCode

Mistake	Fix
API key not exported	Add export to ~/.bashrc or ~/.zshrc
Wrong model name	Check OpenCode docs for exact model names
Port conflict	Use different port or kill existing process
Config file syntax error	Validate JSONC syntax
Missing ~/.config/opencode/	Run opencode once to create config

Claude Code Issues

"Claude Code auth not configured" / "cc_auth_missing"

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
# Follow the prompts

# Check existing auth
cat ~/.claude/settings.json

Rate Limiting / "Rate limit exceeded"

Too many requests to the Anthropic API.

Wait for rate limit to reset (usually 1 minute)
Check your plan limits on the Anthropic dashboard
Session shows "retry" status and auto-retries
Reduce request frequency if persistent

Context Length Exceeded

Session refuses new messages, "Context too long" error.

Use /compact command to summarize and reduce context
Start a new session (context is preserved in history)
Fork the session to create a branch with less history

Permission Issues / "User denied permission"

Tools won't execute, permission prompts timing out.

Check for pending permission prompts in the app
Permission prompt may be waiting on desktop - check there too
Configure permission mode in settings (default, plan, auto-edit)
Use "Allow Always" for trusted tools

"Claude OAuth token expired"

Your Claude login session has expired.

bash

# Re-authenticate
claude login

Common Mistakes - Claude Code

Mistake	Fix
Using wrong API key format	Must start with sk-ant-
API key not exported	Add to shell config or pass via env
Claude CLI not installed	curl -fsSL https://claude.ai/install.sh \| bash
Expired OAuth token	Run claude login again
Denying all permissions	Allow some tools or use auto-edit mode

Codex Issues

Codex is OpenAI's standalone agent

Codex is OpenAI's official CLI agent (like Claude Code is for Anthropic). It has its own tooling system and sandbox.

"Authentication failed"

Codex can't authenticate with OpenAI.

bash

# Re-authenticate
codex --logout
codex

# Or set API key
export OPENAI_API_KEY=sk-...

# Verify the key works
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

"Codex OAuth token expired"

Your Codex/OpenAI login session has expired.

bash

# Re-authenticate
codex
# Follow the login prompts

Rate Limiting / Quota Exceeded

OpenAI rate limits or spending limits reached.

Check your usage on the OpenAI dashboard
Increase spending limits if needed
Wait for rate limit window to reset
Use a different model (e.g., gpt-4o-mini instead of gpt-4o)

Model Not Available

The requested model isn't available for your account.

Some models require waitlist approval
Check model availability on OpenAI dashboard
Try a different model in OpenCode config

Common Mistakes - Codex

Mistake	Fix
Wrong API key format	OpenAI keys start with sk-
Using Claude key for OpenAI	Keys are not interchangeable
Model name typo	Check exact model names on OpenAI docs
Spending limit reached	Increase limit on OpenAI dashboard
Using deprecated model	Update to current model names

Pi Issues

Pi is an open-source multi-provider agent

Pi connects to any AI provider. Most issues relate to provider API key configuration.

"Pi not found"

Bridge can't find the Pi binary.

bash

# Check if Pi is installed
which pi

# If not found, install it
npm i -g @mariozechner/pi-coding-agent

# Then reload your shell
source ~/.bashrc  # or ~/.zshrc

No Models Available

Pi needs at least one AI provider API key to discover models.

bash

# Check your API keys
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
echo $GOOGLE_GENERATIVE_AI_API_KEY

# Set an API key (add to ~/.bashrc or ~/.zshrc)
export ANTHROPIC_API_KEY=sk-ant-...

Context Limit / Auto-Compaction Issues

Session context exceeds model limit.

Use the compact command from the chat overflow menu
Enable auto-compaction in Pi settings
Fork the session to start fresh with a summary
Switch to a model with a larger context window

Extension Errors

A Pi extension is failing or not loading.

Check extension paths in Pi settings
Verify the extension package is installed
Check bridge logs for extension error messages

Common Mistakes - Pi

Mistake	Fix
No API key set	Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or another provider key
Pi not found on PATH	Run npm i -g @mariozechner/pi-coding-agent
Wrong model name	Use the model picker in Broski — Pi auto-discovers available models
Context too long	Use compact command or enable auto-compaction
Extension not loading	Check extension paths and npm package installation

Environment Variables Reference

Variable	Backend	Purpose
`ANTHROPIC_API_KEY`	Claude Code, OpenCode	Anthropic API key
`OPENAI_API_KEY`	OpenCode (Codex)	OpenAI API key
`GOOGLE_AI_API_KEY`	OpenCode	Google Gemini API key
`OPENCODE_PORT`	OpenCode	Server port (default: 4096)
`GROQ_API_KEY`	Pi	Groq API key

Setting Environment Variables Permanently

bash

# Add to ~/.bashrc or ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
echo 'export OPENAI_API_KEY=sk-...' >> ~/.zshrc

# Reload shell config
source ~/.zshrc

Switching Between Backends

You can switch backends in the Broski app:

Go to Settings → AI Backend
Select OpenCode, Claude Code, Codex, or Pi
The bridge will reconnect with the selected backend

Sessions are backend-specific

Sessions created with one backend cannot be opened with another. Each backend maintains its own session history.

General Debugging

bash

# Backend-focused diagnostics
broski doctor --profile agents

# Follow bridge logs
broski logs --follow

# Export diagnostics bundle for support/AI
broski logs --export

# Check backend directly
# For OpenCode:
curl http://localhost:4096/path

# For Claude Code (check if authenticated):
claude --version
cat ~/.claude/settings.json | head -5

# For Pi:
which pi
pi --version

# Check what processes are running
ps aux | grep -E "(opencode|claude|codex|pi|broski)"