Skip to content

troubleshooting.md

Latest commit

 

History

History
239 lines (185 loc) · 5.15 KB

troubleshooting.md

File metadata and controls

239 lines (185 loc) · 5.15 KB

Troubleshooting Guide

Common Issues and Solutions

1. Sync Script Fails: "fetch failed" or "ECONNREFUSED"

Symptom:

❌ Sync failed: fetch failed
   Error: connect ECONNREFUSED 127.0.0.1:1234

Cause: Your AI server is not running or not accessible.

Solutions:

  1. Start your AI server:

    # For LM Studio: Start the application and enable Local Server
# For Ollama: ollama serve
# For vLLM: python -m vllm.entrypoints.openai.api_server --model your-model

  2. Verify endpoint:

    curl http://localhost:1234/v1/models
# Should return JSON with available models

  3. Check firewall/network:

    # Ensure port is accessible
nc -zv localhost 1234

2. "No models found at http://.../v1/models"

Symptom:

⚠️  No models found at http://localhost:1234/v1/models
    Make sure your AI server is running and accessible

Cause: Server running but no models loaded.

Solutions:

  1. For LM Studio: Load a model in the UI
  2. For Ollama: Pull a model first: 
    ollama pull llama3.1:8b
  3. For vLLM: Specify model on startup: 
    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct

3. Sync Works But Models Don't Show in OpenCode

Cause: OpenCode is using a different config file.

Solutions:

  1. Check which config OpenCode is using:

    # Open using custom location
OPENCODE_CONFIG=~/.config/opencode/opencode.json opencode

  2. Verify sync script updated the correct file:

    cat ~/.config/opencode/opencode.json | jq '.provider.local.models'

  3. In OpenCode, check available models:

    # Use /models command within OpenCode

4. "Error reading config (might contain JSON comments?)"

Symptom:

❌ Error reading config (might contain JSON comments?): Unexpected token

Cause: Config file contains comments (JSONC format) that strict JSON parser can't handle.

Solution:

  1. Remove comments from opencode.json
  2. Or use a tool to strip comments before syncing: 
    npm install -g strip-json-comments-cli
strip-json-comments ~/.config/opencode/opencode.json > ~/.config/opencode/opencode.json.clean

5. Bash Functions Not Working After Install

Symptom:

$ opencode
bash: opencode: command not found

Cause: Bash functions not sourced or PATH not updated.

Solutions:

  1. Source your bashrc:

    source ~/.bashrc

  2. Check if functions exist:

    type opencode
# Should show: opencode is a function

  3. Verify OpenCode installation:

    which opencode
# Should show path like /home/user/.opencode/bin/opencode

6. "tools ??= true" Causing Issues

Symptom: Model behaves strangely or tries to call non-existent tools.

Cause: Your model doesn't support tool/function calling.

Solution:

  1. Edit opencode.json and set tools: false for problematic models:

    {
  "provider": {
    "local": {
      "models": {
        "my-small-model": {
          "name": "my-small-model",
          "tools": false
        }
      }
    }
  }
}

  2. Or modify the sync script to detect model capabilities.

7. "Cannot find module '/path/to/sync-local-models.mjs'"

Symptom:

Error: Cannot find module '/home/user/.config/opencode/sync-local-models.mjs'

Cause: Script not installed or path incorrect.

Solution:

  1. Re-run install script:

    ./scripts/install.sh

  2. Or manually copy the scripts:

    cp scripts/providers.mjs ~/.config/opencode/
cp scripts/sync-core.mjs ~/.config/opencode/
cp scripts/sync-provider.mjs ~/.config/opencode/
cp scripts/sync-on-launch.mjs ~/.config/opencode/
cp scripts/sync-local-models.mjs ~/.config/opencode/

8. "Provider not found" or "Model not available"

Symptom:

❌ Error: Provider "xyz" not found

Cause: Provider not synced yet or API key missing.

Solution:

  1. Sync specific provider:

    export LOCAL_API_BASE="https://api.provider.com/v1"
export API_KEY="your-key"
node scripts/sync-provider.mjs

  2. Or sync all providers:

    ./scripts/sync-all-providers.sh

  3. Verify provider exists:

    cat ~/.config/opencode/opencode.json | jq '.provider | keys'

Debugging Tips

Enable Verbose Output

Run sync script with more output:

node ~/.config/opencode/sync-local-models.mjs

Check API Directly

Test your API endpoint:

curl -s http://localhost:1234/v1/models | jq

Verify Config

Check final config:

cat ~/.config/opencode/opencode.json | jq '.provider.local'

Test with Different Endpoints

Override endpoint temporarily:

LOCAL_API_BASE=http://localhost:11434/v1 node scripts/sync-local-models.mjs

Getting Help

If you still have issues:

  1. Check the API Reference
  2. Review OpenCode docs: https://opencode.ai/docs/
  3. Open an issue with:
    • Command you're running
    • Full error output
    • node --version
    • curl $LOCAL_API_BASE/v1/models output
    • Contents of opencode.json