Troubleshooting

This guide covers common issues and their solutions when using OpenCode.

Provider Authentication

Symptoms

• Model requests fail with 401 Unauthorized or 403 Forbidden
• Provider appears in the list but returns errors on use

Diagnosis

# List all configured providers and their auth status
opencode auth list

This shows each provider and whether valid credentials are stored.

Solutions

1. Missing API key: Run /connect in the TUI or use the CLI to add credentials:

   opencode connect <provider>

2. Expired key: Generate a new API key from the provider's dashboard and update via /connect.
3. Wrong environment variable: If setting manually, ensure ANTHROPIC_API_KEY, OPENAI_API_KEY, etc. are exported in your shell.
4. Insufficient quota: Check your provider's billing dashboard for rate limits or quota exhaustion.

Custom Provider Issues

Symptoms

• Custom provider does not appear in model list
• Requests fail with connection errors or unexpected response formats

Diagnosis

Check the provider ID used during /connect matches the provider ID in your opencode.json configuration.

Solutions

1. Mismatched provider ID: The provider ID in /connect must exactly match the key under provider in your config:

   {
     "provider": {
       "my-custom": {
         "baseURL": "https://api.my-custom.com/v1",
         "apiKey": "sk-..."
       }
     }
   }

   Then connect with: /connect my-custom

2. Wrong AI SDK package: Different provider types require different SDK packages:

   Provider Type	npm Package
   OpenAI-compatible	@ai-sdk/openai-compatible
   Cerebras	@ai-sdk/cerebras
   Anthropic	@ai-sdk/anthropic
   OpenAI	@ai-sdk/openai
   Google	@ai-sdk/google

3. Incorrect baseURL: Ensure the baseURL ends with the correct API path prefix. For OpenAI-compatible APIs, it should end with /v1.

4. Missing required headers: Some providers require custom headers:

   {
     "provider": {
       "my-custom": {
         "baseURL": "https://api.example.com/v1",
         "headers": {
           "X-Custom-Auth": "token-here"
         }
       }
     }
   }

Tool Calls Not Working

Symptoms

• Agent says it cannot use a tool
• Tool execution fails silently
• Permission denied errors

Solutions

1. Check permission settings:

   {
     "permission": {
       "read_file": "allow",
       "run_command": "ask",
       "write_file": "allow",
       "glob": "allow",
       "grep": "allow"
     }
   }

   Tools set to "deny" cannot be invoked by the agent.

2. Agent-specific overrides: An agent definition may override global permissions:

   {
     "agent": {
       "my-agent": {
         "permission": {
           "run_command": "deny"
         }
       }
     }
   }

   Check if the agent you are using has restrictive overrides.

3. Tool not available: Verify the tool is installed and configured. List available tools:

   /help

   or check the tool list in the command palette.

4. MCP tools: If using MCP servers, ensure the server is running:

   opencode mcp debug <server-name>

LSP Not Working

Symptoms

• No autocomplete, diagnostics, or go-to-definition
• Language Server features don't respond

Solutions

1. Verify LSP server is installed:

   # TypeScript / JavaScript
   npm install -g typescript-language-server typescript
   
   # Python
   pip install pyright
   
   # Rust
   rustup component add rust-analyzer
   
   # Go
   go install golang.org/x/tools/gopls@latest

2. Check OpenCode LSP configuration:

   {
     "lsp": true
   }

   Or for specific language servers:

   {
     "lsp": {
       "typescript": {
         "command": "typescript-language-server",
         "args": ["--stdio"]
       }
     }
   }

3. Workspace root: LSP requires a project root. Ensure OpenCode is started in a directory with a recognized project file (e.g., package.json, Cargo.toml, go.mod, pyproject.toml).

4. Restart LSP: To restart all language servers, exit OpenCode and re-enter the project directory.

Context Window Full

Symptoms

• Output becomes repetitive or nonsensical
• Agent starts ignoring instructions
• Error about context length exceeded

Solutions

1. Automatic compaction: OpenCode automatically compacts older context when the window approaches the model's limit. This happens transparently.

2. Manual compaction: Trigger compaction explicitly:

   /compact

   or

   /summarize

3. Tune compaction settings: Adjust when and how compaction triggers:

   {
     "compaction": {
       "enabled": true,
       "threshold": 0.8,
       "maxMessages": 100
     }
   }

   • threshold: Fraction of context window at which compaction triggers (0.0 - 1.0)
   • maxMessages: Maximum messages before forced compaction

4. Start fresh: If compaction degrades quality, start a new session:

   /new

MCP Issues

Symptoms

• MCP tools not appearing
• MCP server fails to connect
• Timeout errors with MCP tools

Solutions

1. Debug an MCP server:

   opencode mcp debug <server-name>

   This runs diagnostics including connection tests, tool listing, and resource checks.

2. Verify server configuration:

   {
     "mcp": {
       "my-server": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
         "enabled": true
       }
     }
   }

   Ensure enabled is true and the command is executable.

3. Check server logs: Run the MCP command directly to see error output:

   npx -y @modelcontextprotocol/server-filesystem /workspace

4. Network MCP servers: For url type MCP servers, verify the endpoint is reachable:

   curl -v <mcp-url>

Debug Commands

System Information

opencode debug

This prints system information useful for issue reporting:

• OpenCode version
• Platform and architecture
• Node.js version
• Shell information
• Installed plugins
• Configured providers
• Configuration file paths

Verbose Logging

Run OpenCode with verbose logging to diagnose issues:

# Print all logs to stdout
opencode --print-logs

# Set log level
opencode --log-level debug

# Combine with a specific command
opencode run "Explain this code" --print-logs --log-level debug

Log levels: error, warn, info, debug, trace

Common Error Messages

Error	Likely Cause	Solution
ENOTFOUND api.anthropic.com	DNS resolution failure	Check network connectivity and DNS settings
ECONNREFUSED	Provider endpoint not reachable	Verify baseURL and that the service is running
401 Unauthorized	Invalid or missing API key	Run opencode auth list and reconnect provider
429 Too Many Requests	Rate limited	Wait and retry, or upgrade API plan
ContextLengthExceeded	Too many tokens	Run /compact or start a new session
Tool execution denied	Permission not granted	Check permission config for the tool

Getting Help

If you continue to experience issues:

• Search existing GitHub issues
• Ask on Discord with the output of opencode debug
• Provide logs: opencode --print-logs --log-level debug > opencode.log 2>&1