> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions when using OpenCode

This guide covers common issues you might encounter while using OpenCode and their solutions.

## Installation issues

<AccordionGroup>
  <Accordion title="Command not found: opencode">
    **Symptoms:** Running `opencode` returns "command not found"

    **Solution:**

    <Steps>
      <Step title="Verify installation">
        Check if OpenCode is installed:

        ```bash theme={null}
        which opencode
        ```
      </Step>

      <Step title="Update PATH">
        If installed via Go:

        ```bash theme={null}
        # Add to ~/.bashrc or ~/.zshrc
        export PATH="$PATH:$HOME/go/bin"
        ```

        Then reload your shell:

        ```bash theme={null}
        source ~/.bashrc  # or ~/.zshrc
        ```
      </Step>

      <Step title="Reinstall if necessary">
        Try reinstalling OpenCode:

        ```bash theme={null}
        # Using Homebrew
        brew reinstall opencode-ai/tap/opencode

        # Using Go
        go install github.com/opencode-ai/opencode@latest
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Permission denied errors">
    **Symptoms:** Permission errors when installing or running OpenCode

    **Solution:**

    ```bash theme={null}
    # If installed globally, ensure proper permissions
    sudo chown -R $(whoami) /usr/local/bin/opencode

    # Or install for current user only
    go install github.com/opencode-ai/opencode@latest
    ```
  </Accordion>
</AccordionGroup>

## Configuration issues

<AccordionGroup>
  <Accordion title="Config file not found">
    **Symptoms:** OpenCode doesn't find your configuration file

    **Solution:**

    OpenCode looks for configuration in these locations (in order):

    1. `./.opencode.json` (current directory)
    2. `$XDG_CONFIG_HOME/opencode/.opencode.json`
    3. `$HOME/.opencode.json`

    Create a config file in one of these locations:

    ```bash theme={null}
    # Option 1: Home directory
    touch ~/.opencode.json

    # Option 2: XDG config directory
    mkdir -p ~/.config/opencode
    touch ~/.config/opencode/.opencode.json
    ```
  </Accordion>

  <Accordion title="Invalid JSON in config file">
    **Symptoms:** OpenCode fails to start with JSON parsing error

    **Solution:**

    Validate your JSON:

    ```bash theme={null}
    # Use jq to validate and format
    jq . ~/.opencode.json
    ```

    Common JSON errors:

    * Missing commas between properties
    * Trailing commas (not allowed in JSON)
    * Unquoted keys or values
    * Unclosed brackets or braces

    Example of valid JSON:

    ```json theme={null}
    {
      "providers": {
        "anthropic": {
          "apiKey": "your-key",
          "disabled": false
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Model not found or unsupported">
    **Symptoms:** Error message about unsupported or unavailable model

    **Solution:**

    <Steps>
      <Step title="Check model name">
        Ensure the model ID is correct. See the [quickstart guide](/quickstart) for supported models.
      </Step>

      <Step title="Verify provider is configured">
        Check that the provider for your model is properly configured:

        ```bash theme={null}
        # For Anthropic
        echo $ANTHROPIC_API_KEY

        # For OpenAI
        echo $OPENAI_API_KEY
        ```
      </Step>

      <Step title="Check provider status">
        Ensure the provider isn't disabled:

        ```json .opencode.json theme={null}
        {
          "providers": {
            "anthropic": {
              "disabled": false  // Should be false
            }
          }
        }
        ```
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Provider and API issues

<AccordionGroup>
  <Accordion title="API key not working">
    **Symptoms:** Authentication errors with your API key

    **Solution:**

    <Steps>
      <Step title="Verify API key is valid">
        * Check for extra spaces or newlines
        * Ensure the key hasn't expired
        * Verify the key has the correct permissions
      </Step>

      <Step title="Check environment variables">
        ```bash theme={null}
        # List all OpenCode-related env vars
        env | grep -E '(ANTHROPIC|OPENAI|GEMINI|GITHUB)'
        ```
      </Step>

      <Step title="Test API key directly">
        Test your API key with curl:

        ```bash theme={null}
        # Anthropic
        curl https://api.anthropic.com/v1/messages \
          -H "x-api-key: $ANTHROPIC_API_KEY" \
          -H "content-type: application/json" \
          -d '{"model":"claude-4-sonnet-20250514","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

        # OpenAI
        curl https://api.openai.com/v1/models \
          -H "Authorization: Bearer $OPENAI_API_KEY"
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Rate limit errors">
    **Symptoms:** Error messages about rate limits or too many requests

    **Solution:**

    OpenCode automatically retries rate-limited requests with exponential backoff (up to 8 retries).

    If you continue to hit rate limits:

    * **Wait:** Rate limits typically reset after a few minutes
    * **Upgrade:** Consider upgrading your API tier
    * **Reduce load:** Use smaller models for simple tasks
    * **Monitor usage:** Check your API usage dashboard

    <Info>
      OpenCode respects `Retry-After` headers and implements exponential backoff automatically.
    </Info>
  </Accordion>

  <Accordion title="Connection timeout">
    **Symptoms:** Requests timeout or hang indefinitely

    **Solution:**

    <Steps>
      <Step title="Check network connection">
        Verify you can reach the API:

        ```bash theme={null}
        ping api.anthropic.com
        ping api.openai.com
        ```
      </Step>

      <Step title="Check firewall and proxy settings">
        * Ensure your firewall allows HTTPS traffic
        * If behind a corporate proxy, configure proxy settings
        * Check VPN isn't blocking API access
      </Step>

      <Step title="Verify API status">
        Check provider status pages:

        * [Anthropic Status](https://status.anthropic.com)
        * [OpenAI Status](https://status.openai.com)
        * [Google Cloud Status](https://status.cloud.google.com)
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Context length exceeded">
    **Symptoms:** Error about exceeding maximum context length

    **Solution:**

    <Warning>
      This error occurs when your conversation exceeds the model's context window.
    </Warning>

    Options:

    1. **Enable auto-compact** (enabled by default):

       ```json .opencode.json theme={null}
       {
         "autoCompact": true
       }
       ```

       This automatically summarizes your conversation when approaching the limit.

    2. **Manually compact** the session using `Ctrl+K` → "Compact Session"

    3. **Start a new session** with `Ctrl+N`

    4. **Use a model with a larger context window**:
       * Claude 4 Sonnet: 200K tokens
       * Gemini 2.5: 1M tokens
       * GPT-4.1: 128K tokens
  </Accordion>
</AccordionGroup>

## GitHub Copilot issues

<AccordionGroup>
  <Accordion title="GitHub token not found">
    **Symptoms:** OpenCode can't find your GitHub Copilot token

    **Solution:**

    <Steps>
      <Step title="Authenticate with GitHub CLI">
        ```bash theme={null}
        gh auth login
        ```
      </Step>

      <Step title="Or set token explicitly">
        ```bash theme={null}
        export GITHUB_TOKEN="ghp_your_token_here"
        ```
      </Step>

      <Step title="Verify token location">
        Check that the token file exists:

        ```bash theme={null}
        ls -la ~/.config/github-copilot/
        ```
      </Step>
    </Steps>

    See the [GitHub Copilot guide](/advanced/github-copilot) for more details.
  </Accordion>

  <Accordion title="Copilot token exchange failed">
    **Symptoms:** Error exchanging GitHub token for Copilot bearer token

    **Solution:**

    * Ensure Copilot chat is enabled in your [GitHub settings](https://github.com/settings/copilot)
    * Verify your Copilot subscription is active
    * Check that your GitHub token has Copilot permissions
    * Try re-authenticating with the GitHub CLI
  </Accordion>
</AccordionGroup>

## Self-hosted model issues

<AccordionGroup>
  <Accordion title="Cannot connect to local endpoint">
    **Symptoms:** Connection refused to local model endpoint

    **Solution:**

    <Steps>
      <Step title="Verify server is running">
        ```bash theme={null}
        # Check if the port is listening
        netstat -an | grep :1234
        # or
        lsof -i :1234
        ```
      </Step>

      <Step title="Test endpoint">
        ```bash theme={null}
        curl http://localhost:1234/v1/models
        ```
      </Step>

      <Step title="Check LOCAL_ENDPOINT variable">
        ```bash theme={null}
        echo $LOCAL_ENDPOINT
        # Should output: http://localhost:1234/v1
        ```
      </Step>
    </Steps>

    See the [self-hosted models guide](/advanced/self-hosted-models) for more details.
  </Accordion>

  <Accordion title="Model doesn't support tool calling">
    **Symptoms:** Self-hosted model doesn't use tools correctly

    **Solution:**

    Not all models support tool/function calling. Use models known to work well:

    * Llama 3.3 70B Instruct
    * Qwen 2.5 Coder
    * Granite 3.1 (IBM)
    * Mistral Large

    Ensure your inference server properly implements the OpenAI tools API.
  </Accordion>
</AccordionGroup>

## Shell and command execution issues

<AccordionGroup>
  <Accordion title="Commands not found in shell">
    **Symptoms:** Tools like `npm`, `python`, or custom scripts aren't found

    **Solution:**

    Use a login shell to load your PATH:

    ```json .opencode.json theme={null}
    {
      "shell": {
        "path": "/bin/bash",
        "args": ["-l"]
      }
    }
    ```

    See the [shell configuration guide](/advanced/shell-configuration) for more details.
  </Accordion>

  <Accordion title="Environment variables not available">
    **Symptoms:** Environment variables set in your profile aren't available

    **Solution:**

    Ensure variables are exported in your profile:

    ```bash ~/.bash_profile theme={null}
    export NODE_PATH="/usr/local/lib/node_modules"
    export PATH="$HOME/.local/bin:$PATH"
    ```

    And use a login shell configuration.
  </Accordion>

  <Accordion title="Command execution timeout">
    **Symptoms:** Long-running commands are killed

    **Solution:**

    OpenCode uses a default timeout of 2 minutes for commands. For long-running operations:

    * Break down the operation into smaller steps
    * Ask OpenCode to run the command with explicit timeout handling
    * Consider running the command outside of OpenCode for very long operations
  </Accordion>
</AccordionGroup>

## Database and session issues

<AccordionGroup>
  <Accordion title="Database locked error">
    **Symptoms:** SQLite database lock errors

    **Solution:**

    This usually means another OpenCode instance is running.

    <Steps>
      <Step title="Close other instances">
        Check for running OpenCode processes:

        ```bash theme={null}
        ps aux | grep opencode
        ```

        Kill any orphaned processes:

        ```bash theme={null}
        killall opencode
        ```
      </Step>

      <Step title="Remove lock file">
        If the issue persists:

        ```bash theme={null}
        rm ~/.opencode/.db-lock
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Session history lost">
    **Symptoms:** Previous conversations don't appear

    **Solution:**

    Check the database file exists:

    ```bash theme={null}
    ls -la ~/.opencode/opencode.db
    ```

    If the database is corrupted, you may need to remove it (this will delete all sessions):

    ```bash theme={null}
    # Backup first
    cp ~/.opencode/opencode.db ~/.opencode/opencode.db.backup

    # Remove corrupted database
    rm ~/.opencode/opencode.db
    ```
  </Accordion>

  <Accordion title="Cannot switch sessions">
    **Symptoms:** Session switching (Ctrl+A) doesn't work

    **Solution:**

    * Ensure you have multiple sessions created
    * Try creating a new session with `Ctrl+N` first
    * Check if the database is accessible
    * Restart OpenCode
  </Accordion>
</AccordionGroup>

## Performance issues

<AccordionGroup>
  <Accordion title="Slow startup time">
    **Symptoms:** OpenCode takes a long time to start

    **Solution:**

    <Steps>
      <Step title="Check shell startup time">
        Your shell profile might be slow to load:

        ```bash theme={null}
        time bash -l -c 'echo loaded'
        ```
      </Step>

      <Step title="Optimize shell profile">
        * Remove unnecessary initialization
        * Lazy-load plugins and tools
        * Profile your shell config to find slow parts
      </Step>

      <Step title="Check database size">
        Large databases can slow startup:

        ```bash theme={null}
        ls -lh ~/.opencode/opencode.db
        ```

        Consider archiving old sessions.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="High memory usage">
    **Symptoms:** OpenCode uses excessive memory

    **Solution:**

    * Use models with smaller context windows
    * Compact long sessions
    * Restart OpenCode periodically
    * Check for memory leaks (report as a bug if persistent)
  </Accordion>

  <Accordion title="Slow response generation">
    **Symptoms:** Responses take a long time to generate

    **Solution:**

    * Use faster models (e.g., GPT-4o Mini, Claude Haiku)
    * Reduce `maxTokens` for faster responses
    * Check your network connection
    * Consider using a different provider or region
  </Accordion>
</AccordionGroup>

## LSP integration issues

<AccordionGroup>
  <Accordion title="LSP server not starting">
    **Symptoms:** Language server features don't work

    **Solution:**

    <Steps>
      <Step title="Verify LSP server is installed">
        ```bash theme={null}
        which gopls  # for Go
        which typescript-language-server  # for TypeScript
        ```
      </Step>

      <Step title="Check LSP configuration">
        ```json .opencode.json theme={null}
        {
          "lsp": {
            "go": {
              "disabled": false,
              "command": "gopls"
            }
          }
        }
        ```
      </Step>

      <Step title="Enable LSP debug logging">
        ```json .opencode.json theme={null}
        {
          "debugLSP": true
        }
        ```

        Then check logs with `Ctrl+L`
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="LSP diagnostics not showing">
    **Symptoms:** OpenCode doesn't show code errors or warnings

    **Solution:**

    * Ensure the LSP server supports diagnostics
    * Check that files are saved (LSP typically works on saved files)
    * Verify the language server is properly initialized
    * Try restarting OpenCode
  </Accordion>
</AccordionGroup>

## Getting help

If you're still experiencing issues:

<CardGroup cols={2}>
  <Card title="Enable debug mode" icon="bug">
    Run OpenCode with debug logging:

    ```bash theme={null}
    opencode -d
    ```

    View logs with `Ctrl+L`
  </Card>

  <Card title="Check GitHub issues" icon="github">
    Search for similar issues:

    [github.com/opencode-ai/opencode/issues](https://github.com/opencode-ai/opencode/issues)
  </Card>

  <Card title="Report a bug" icon="flag">
    Create a new issue with:

    * OpenCode version
    * Operating system
    * Error messages
    * Debug logs
  </Card>

  <Card title="Join the community" icon="users">
    Get help from other users and contributors in discussions.
  </Card>
</CardGroup>

## Useful debug commands

```bash theme={null}
# Check OpenCode version
opencode --version

# Run with debug output
opencode -d

# Check configuration
cat ~/.opencode.json | jq .

# Verify environment variables
env | grep -E '(ANTHROPIC|OPENAI|GEMINI|GITHUB|AWS|AZURE)'

# Test API connectivity
curl https://api.anthropic.com/v1/messages -I
curl https://api.openai.com/v1/models -I

# Check database
ls -lh ~/.opencode/opencode.db
sqlite3 ~/.opencode/opencode.db "SELECT COUNT(*) FROM sessions;"

# View recent logs
tail -f ~/.opencode/debug.log  # if OPENCODE_DEV_DEBUG=true
```