AI Backend Issues

Troubleshoot issues specific to OpenCode, Claude Code, and Codex 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

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)

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, or Codex
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

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