Troubleshooting - OpenCode

This guide covers common issues, debugging techniques, and solutions for OpenCode problems.

Diagnostic Steps

Before diving into specific issues, gather diagnostic information:

Check logs

Log files are your first stop for debugging:

macOS/Linux
Windows

ls -ltr ~/.local/share/opencode/log/
tail -f ~/.local/share/opencode/log/$(ls -t ~/.local/share/opencode/log/ | head -1)

# Press WIN+R, paste:
%USERPROFILE%\.local\share\opencode\log

# View latest log
Get-Content (Get-ChildItem $env:USERPROFILE\.local\share\opencode\log | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName -Tail 50

Increase log verbosity

opencode --log-level DEBUG

Or set persistently:

opencode.json

{
  "logLevel": "debug"
}

Check version

opencode --version

Ensure you’re on the latest version:

opencode upgrade

Verify storage health

# Check for corruption
sqlite3 ~/.local/share/opencode/project/*/storage/*.db "PRAGMA integrity_check;"

Common Issues

OpenCode Won’t Start

Symptom: Command not found

Error:

bash: opencode: command not found

Cause: Binary not in PATH or installation incomplete.Solutions:

Verify installation

which opencode
# Should print: /usr/local/bin/opencode or ~/.local/bin/opencode

Reinstall if missing

curl -fsSL https://opencode.ai/install | bash

Add to PATH manually

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Restart terminal

Close and reopen your terminal window.

Symptom: Crashes immediately

Error: OpenCode starts then exits within seconds.Debugging:

# Run with logs to stdout
opencode --print-logs

# Check for specific error messages
tail -100 ~/.local/share/opencode/log/*.log | grep -i error

Common causes:

Port conflict

# Find process using port 4096
lsof -i :4096

# Kill conflicting process
kill -9 <PID>

# Or use different port
opencode --port 4097

Corrupted config

# Backup and reset config
mv ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak
opencode

Permission errors

# Fix permissions
chmod -R u+rwX ~/.local/share/opencode
chmod -R u+rwX ~/.config/opencode

Symptom: Blank screen or frozen UI

Symptoms: TUI starts but shows nothing or freezes.Quick fixes:

Force redraw:
- Press Ctrl+L to redraw screen

Check terminal compatibility:

echo $TERM
# Should be: xterm-256color, screen-256color, or similar

If not, set it:

export TERM=xterm-256color
opencode

Try different terminal:
- macOS: iTerm2, Alacritty, or native Terminal.app
- Linux: gnome-terminal, konsole, alacritty
- Windows: Windows Terminal, not Command Prompt

Authentication Issues

Cannot connect to provider

Error:

ProviderAuthError: Failed to authenticate with openai

Solutions:

Verify API key

# Check key is set
cat ~/.local/share/opencode/auth.json | jq '.openai'

# Test key directly
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

Re-authenticate

# In OpenCode TUI
/connect

# Or via API
curl -X PUT http://localhost:4096/auth/openai \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "sk-..."}'

Check network connectivity

# Test provider API access
curl -I https://api.openai.com
curl -I https://api.anthropic.com

If these fail, check proxy settings (see Network Configuration).

API key works elsewhere but not in OpenCode

Cause: Key format issue or whitespace.Fix:

# Remove auth.json and re-add
rm ~/.local/share/opencode/auth.json
opencode
# Use /connect command

Ensure no leading/trailing whitespace:

# Wrong:
"apiKey": " sk-abc123 "

# Correct:
"apiKey": "sk-abc123"

Model Errors

ProviderModelNotFoundError

Error:

ProviderModelNotFoundError: Model "gpt-4" not found

Cause: Incorrect model reference format.Solution:Models must be referenced as <providerID>/<modelID>:

{
  "model": "openai/gpt-4.1"
}

{
  "model": "gpt-4"  // Missing provider
}

List available models:

opencode models

# Or via API
curl http://localhost:4096/provider

Common model IDs:

openai/gpt-4.1
openai/gpt-4.1-mini
anthropic/claude-4.5-sonnet
openrouter/google/gemini-2.5-flash

Model not available

Error:

Model "openai/gpt-4" requires higher tier access

Causes:

Model requires paid subscription
Account doesn’t have access
Model deprecated/renamed

Check access:

# List models you have access to
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | jq '.data[].id'

Fallback to available model:

opencode.json

{
  "model": "openai/gpt-4.1-mini"  // Free tier alternative
}

Provider Package Issues

AI_APICallError: Outdated provider packages

Symptoms:

API errors mentioning unknown parameters
“Unexpected field” errors
Sudden failures after provider API updates

Cause: Cached provider packages (OpenAI SDK, Anthropic SDK, etc.) are outdated.Solution:

Clear provider cache

macOS/Linux
Windows

rm -rf ~/.cache/opencode

Remove-Item -Recurse -Force $env:USERPROFILE\.cache\opencode

Restart OpenCode

opencode

OpenCode will automatically download the latest provider packages.

Verify fix

Check logs for successful package installation:

tail -f ~/.local/share/opencode/log/*.log | grep -i "installed"

Provider packages are cached in ~/.cache/opencode to speed up startup. Clear this if you encounter API compatibility issues.

Configuration Issues

ProviderInitError

Error:

ProviderInitError: Failed to initialize provider "openai"

Cause: Corrupted or invalid configuration.Fix:

Validate config syntax

# Check for JSON errors
cat ~/.config/opencode/opencode.json | jq .
# Should output formatted JSON

Reset config

# Backup
cp ~/.config/opencode/opencode.json{,.bak}

# Reset to minimal config
cat > ~/.config/opencode/opencode.json <<EOF
{
  "$schema": "https://opncd.ai/config.json"
}
EOF

Clear cached data

rm -rf ~/.local/share/opencode

This deletes all sessions and history. Backup first if needed.

Re-authenticate

opencode
# Run /connect command

Config changes not taking effect

Cause: Config cached or syntax error preventing reload.Solutions:

Restart OpenCode:

# Kill existing instance
pkill -f opencode

# Start fresh
opencode

Verify config location:
```
# Check which config is loaded
opencode --print-logs 2>&1 | grep -i config
```
Config priority:
1. .opencode/opencode.json (project-specific)
2. ~/.config/opencode/opencode.json (user-specific)

Validate syntax:

# Must be valid JSON (no comments unless .jsonc)
cat ~/.config/opencode/opencode.json | jq .

Desktop App Issues

App won't launch

Quick checks:

Fully quit and relaunch:
- macOS: Cmd+Q, then reopen
- Windows: Right-click tray icon → Exit, then reopen
Check for error dialog:
- Click “Restart” button if shown
- Copy error details for debugging
macOS only - Reload webview:
- Menu: OpenCode → Reload Webview
- Helps if UI is blank/frozen

Connection failed

Symptoms: “Connection Failed” dialog on launch.Causes:

Custom server URL is unreachable
Port conflict preventing local server start
Firewall blocking connection

Solutions:

Clear custom server URL

From Home screen:

Click server name (with status dot)
Click “Clear” in Default server section
Restart app

Remove server config

Edit ~/.config/opencode/opencode.json, remove:

{
  "server": {
    "port": 4096,
    "hostname": "..."
  }
}

Check environment variables

# Unset if present
unset OPENCODE_PORT
unset OPENCODE_HOSTNAME

Plugin causing crashes

Symptoms: App crashes on launch after installing plugin.Fix: Disable plugins

Edit global config

Open:

macOS/Linux: ~/.config/opencode/opencode.jsonc
Windows: %USERPROFILE%\.config\opencode\opencode.jsonc

Set:

{
  "plugin": []  // Empty array disables all
}

Move plugin files

Rename plugin directories:

# Global plugins
mv ~/.config/opencode/plugins ~/.config/opencode/plugins.disabled

# Project plugins
mv .opencode/plugins .opencode/plugins.disabled

Restart and re-enable one by one

Once app works, re-enable plugins individually to find the culprit.

Clear app cache

When: App behaves strangely, plugin install stuck.

macOS
Linux
Windows

# Quit app first
rm -rf ~/Library/Caches/ai.opencode.*
rm -rf ~/.cache/opencode

# Quit app first
rm -rf ~/.cache/opencode

Press WIN+R, paste:

%USERPROFILE%\.cache\opencode

Delete the folder, then restart app.

Notifications not showing

Requirements:

Notifications enabled in OS settings for OpenCode
App window not focused (notifications only show when backgrounded)

Enable notifications:

macOS
Windows
Linux

System Settings → Notifications → OpenCode → Allow Notifications ✓

Linux-Specific Issues

Copy/paste not working

Cause: Missing clipboard utilities.Solution: Install clipboard tools

X11 (most common)
Wayland
Headless (SSH/Docker)

# Debian/Ubuntu
sudo apt install -y xclip

# Or alternative
sudo apt install -y xsel

# RHEL/CentOS
sudo yum install -y xclip

# Debian/Ubuntu
sudo apt install -y wl-clipboard

# Fedora
sudo dnf install -y wl-clipboard

# Install virtual display
sudo apt install -y xvfb

# Start virtual display
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

# Now install xclip
sudo apt install -y xclip

Verify fix:

echo "test" | xclip -selection clipboard
xclip -selection clipboard -o
# Should output: test

Wayland compositor issues

Symptoms: Blank window, crashes on Linux with Wayland.Try Wayland flag:

OC_ALLOW_WAYLAND=1 opencode

If worse, use X11 session:

Log out
At login screen, select “Ubuntu on Xorg” or “GNOME on Xorg”
Log in and launch OpenCode

Windows-Specific Issues

WebView2 missing

Error: App opens to blank window (Windows only).Cause: Microsoft Edge WebView2 Runtime not installed.Solution:

Download WebView2 Runtime

Download from Microsoft

Install the downloaded MSI

Run the installer and follow prompts.

Restart OpenCode Desktop

Should now display correctly.

Performance issues

Symptoms: Slow file operations, laggy terminal, high CPU.Recommended: Use WSLSee Windows WSL Guide for optimal Windows setup.WSL provides:

10-20x faster file I/O
Better terminal support
Native Linux tool compatibility

Advanced Debugging

Enable Debug Logging

# Maximum verbosity
export DEBUG="*"
export LOG_LEVEL="debug"
opencode --log-level DEBUG --print-logs

Inspect Database

OpenCode uses SQLite for storage:

# List databases
find ~/.local/share/opencode -name "*.db"

# Open database
sqlite3 ~/.local/share/opencode/project/<slug>/storage/session.db

# Useful queries
SELECT * FROM session ORDER BY updated_at DESC LIMIT 5;
SELECT COUNT(*) FROM message;
PRAGMA table_info(session);

Network Debugging

# Trace HTTP requests
export DEBUG="http*"
opencode

# Test proxy connectivity
curl -x $HTTPS_PROXY https://api.openai.com/v1/models

# Check certificate issues
openssl s_client -connect api.openai.com:443 -showcerts

Profile Performance

# CPU profiling (Bun runtime)
bun --inspect opencode

# Memory usage
top -p $(pgrep -f opencode)

# Disk I/O
iotop -p $(pgrep -f opencode)

Reset Everything (Last Resort)

This deletes all OpenCode data including sessions, history, and configuration.Backup important sessions before proceeding.

macOS/Linux
Windows

# Backup (optional)
tar -czf ~/opencode-backup-$(date +%Y%m%d).tar.gz \
  ~/.local/share/opencode \
  ~/.config/opencode \
  ~/.cache/opencode

# Delete all data
rm -rf ~/.local/share/opencode
rm -rf ~/.config/opencode
rm -rf ~/.cache/opencode

# Reinstall
curl -fsSL https://opencode.ai/install | bash

# Start fresh
opencode

# Backup (optional)
Compress-Archive -Path "$env:USERPROFILE\.local\share\opencode","$env:USERPROFILE\.config\opencode","$env:USERPROFILE\.cache\opencode" -DestinationPath "$env:USERPROFILE\opencode-backup-$(Get-Date -Format 'yyyyMMdd').zip"

# Delete all data
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\opencode"
Remove-Item -Recurse -Force "$env:USERPROFILE\.config\opencode"
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode"

# Reinstall
irm https://opencode.ai/install.ps1 | iex

# Start fresh
opencode

Getting Help

GitHub Issues

Report bugs and request features. Search existing issues first.

Discord Community

Real-time help from the community and maintainers.

Documentation

Comprehensive guides and API references.

Enterprise Support

Priority support for enterprise customers.

When Reporting Issues

Include this information:

System Information

# Copy output of:
opencode --version
uname -a  # or ver on Windows
node --version
echo $SHELL

Error Logs

# Include relevant log excerpts
tail -100 ~/.local/share/opencode/log/*.log

Redact sensitive info (API keys, file paths).

Configuration

# Share config (redact secrets)
cat ~/.config/opencode/opencode.json

Reproduction Steps

Step-by-step instructions to reproduce
Expected behavior
Actual behavior
Screenshots/screencasts if applicable

Preventive Measures

Keep Updated

opencode upgrade

Run monthly to get latest fixes.

Backup Sessions

# Periodic backups
tar -czf ~/opencode-backup.tar.gz ~/.local/share/opencode/project

Monitor Logs

Check logs after updates:

tail -f ~/.local/share/opencode/log/*.log

Test Config Changes

Test config in isolated session:

opencode --config /tmp/test-config.json

Next Steps

Server Configuration

Advanced server setup and debugging.

Network Setup

Resolve proxy and certificate issues.

Windows WSL

Fix Windows-specific performance issues.

​Diagnostic Steps

​Common Issues

​OpenCode Won’t Start

​Authentication Issues

​Model Errors

​Provider Package Issues

​Configuration Issues

​Desktop App Issues

​Linux-Specific Issues

​Windows-Specific Issues

​Advanced Debugging

​Enable Debug Logging

​Inspect Database

​Network Debugging

​Profile Performance

​Reset Everything (Last Resort)

​Getting Help

GitHub Issues

Discord Community

Documentation

Enterprise Support

​When Reporting Issues

​Preventive Measures

Keep Updated

Backup Sessions

Monitor Logs

Test Config Changes

​Next Steps

Server Configuration

Network Setup

Windows WSL

Diagnostic Steps

Common Issues

OpenCode Won’t Start

Authentication Issues

Model Errors

Provider Package Issues

Configuration Issues

Desktop App Issues

Linux-Specific Issues

Windows-Specific Issues

Advanced Debugging

Enable Debug Logging

Inspect Database

Network Debugging

Profile Performance

Reset Everything (Last Resort)

Getting Help

When Reporting Issues

Preventive Measures

Next Steps