Troubleshooting

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

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.

Get Started

Core Concepts

Configuration

Integrations

Extensibility

Interfaces

Advanced

Enterprise

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

Get Started

Core Concepts

Configuration

Integrations

Extensibility

Interfaces

Advanced

Enterprise

​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