troubleshooting.md

🔧 Troubleshooting

❓ FAQ

Requests hang, but /v1/models works

Set OPENCODE_USE_ISOLATED_HOME=false so OpenCode reuses the host login state:

OPENCODE_USE_ISOLATED_HOME=false

Free models fail with free tier can only be used from within OpenCode

The backend is not loading the tool-lock plugin. Let the proxy start the backend (default MANAGE_BACKEND=true), or add plugin/opencode2api-tool-lock.js to your own backend's plugin config.

Model not found (model_not_found)

Check the model ID against the backend:

curl http://127.0.0.1:10000/v1/models

Sent reasoning_effort but got no reasoning output

Use the Responses API with stream: true, and pass reasoning.effort or reasoning_effort.

Client unexpectedly triggers OpenCode built-in tools

Keep OPENCODE_DISABLE_TOOLS=true.

Port conflict (EADDRINUSE)

# Check usage
lsof -i :10000
lsof -i :10001

# Change ports
OPENCODE_PROXY_PORT=10002
OPENCODE_SERVER_PORT=10003

OpenCode not installed (Cannot verify OpenCode installation)

npm install -g opencode-ai@1.19.0
# Or curl -fsSL https://opencode.ai/install | bash

You can also point to the full binary path via OPENCODE_PATH.

Empty model list / completions fail, logs show /config/providers errors

The installed backend is OpenCode 2.x. This proxy currently supports OpenCode 1.x backends only and refuses 2.x at startup with OpenCode backend 2.x is not compatible. Install the newest 1.x release:

npm install -g opencode-ai@1.19.0
# or point OPENCODE_PATH at a 1.x binary

Keep OpenCode on 1.x and do not upgrade until the proxy announces 2.x support.

Docker container fails to start

docker compose logs
netstat -tulpn | grep -E '10000|10001'

Auth failure (401 Unauthorized)

Confirm the request carries the same Bearer token as API_KEY:

curl -H "Authorization: Bearer YOUR_API_KEY" ...

🔍 Debug Mode

OPENCODE_PROXY_DEBUG=true

Debug logs print detailed request and response info.

🆘 Get Help

• 🐛 GitHub Issues