OpenCode Go Troubleshooting

Guía de diagnóstico y reparación cuando OpenCode no funciona con una suscripción OpenCode Go: prompts que no responden, Insufficient balance, Rate limit exceeded o Authentication Fails.

Probado en: OpenCode CLI 1.18.11 (npm) sobre WSL/Ubuntu, agosto 2026.

---

Índice

1. Síntomas
2. Causas raíz (4)
3. Explicación detallada
4. Diagnóstico reproducible
5. Verificación final
6. Archivos tocados
7. Lecciones

---

1. Síntomas

• El prompt se escribe y "no pasa nada" (o error silencioso).
• opencode run "..." termina sin respuesta del modelo.
• Errores en consola:
  • Insufficient balance. Manage your billing here: https://opencode.ai/workspace/<WS_ID>/billing
  • Rate limit exceeded. Please try again later.
  • Unauthorized: Authentication Fails (governor) (solo providers custom)

2. Causas raíz

#	Causa	Efecto
1	Base de datos SQLite de sesiones corrupta	TODO mensaje falla al insertarse: opencode parece muerto
2	Modelo con prefijo opencode/* (Zen prepago) en vez de opencode-go/*	"Insufficient balance" aunque la suscripción Go esté activa
3	Paquete npm @ai-sdk/openai-compatible no instalado (auto-install falló)	Providers custom (DeepSeek/Groq directos) fallan
4	{env:VAR} en config solo resuelve si la variable está exportada en el shell	Peticiones SIN header Authorization → "Authentication Fails"

3. Explicación detallada

3.1 DB de sesiones corrupta

OpenCode guarda sesiones y mensajes en SQLite:

~/.local/share/opencode/opencode.db   (junto a -wal y -shm)

Firma en el log (~/.local/share/opencode/log/opencode.log):

level=ERROR ... SQLiteError: database disk image is malformed
... Failed query: insert into "message" ...

Cada prompt dispara un INSERT; si la DB está corrupta, la conversación no arranca — aparenta un problema de proveedor/key cuando en realidad el CLI no puede persistir nada. Causas típicas: WSL shutdown con opencode abierto, crashes, WAL dañado. El sqlite3 del sistema puede dar "header and source version mismatch" (versión vieja): el error real está en el log de opencode.

Reparación: respaldar y recrear:

mkdir -p ~/opencode-db-backup
cd ~/.local/share/opencode
cp opencode.db opencode.db-wal opencode.db-shm ~/opencode-db-backup/ 2>/dev/null
rm opencode.db opencode.db-wal opencode.db-shm
# opencode recrea la DB limpia en el próximo arranque

Se pierde el historial de sesiones (el respaldo queda para recuperación).

3.2 El prefijo de provider: opencode vs opencode-go (hallazgo clave)

El catálogo models.dev define DOS providers para el mismo servicio:

Provider	Endpoint	Modelos	Facturación
opencode	https://opencode.ai/zen/v1	85	Saldo prepago (balance USD > 0)
opencode-go	https://opencode.ai/zen/go/v1	23	Suscripción Go ($5 1er mes, $10/mes, límites de uso)

Lógica del gateway (packages/console/app/src/routes/zen/util/handler.ts):

- modelo "lite" (Go)  → requiere billing.lite (suscripción activa) → funciona
- modelo "full" (Zen) → si billing.balance <= 0 → "Insufficient balance"

Con suscripción Go activa, los modelos opencode/* SIEMPRE dan "Insufficient balance" porque /zen/v1 chequea el saldo prepago, no la suscripción.

Verificación con la misma API key:

# Endpoint Zen (full) — falla con balance 0:
curl -X POST https://opencode.ai/zen/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":1}'
# → CreditsError "Insufficient balance" (HTTP 401)

# Endpoint Go (lite) — funciona con suscripción activa:
curl -X POST https://opencode.ai/zen/go/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":1}'
# → chat.completion normal, "cost":"0" (HTTP 200)

Fix:

// ~/.config/opencode/opencode.jsonc
{
  "model": "opencode-go/deepseek-v4-flash",
  "small_model": "opencode-go/deepseek-v4-flash"
}

Modelos Go (17): deepseek-v4-flash, deepseek-v4-pro, grok-4.5, kimi-k3, kimi-k2.7-code, glm-5.2, glm-5.1, gpt-5.6-luna, qwen3.7-max, qwen3.7-plus, qwen3.6-plus, minimax-m3, minimax-m2.7, mimo-v2.5, mimo-v2.5-pro, hy3.

Notas de facturación Go:

• Límites: $12 de uso por 5h, $30/semana, $60/mes (en USD de uso, no requests).
• Modelos free (opencode/*-free) como fallback, con rate-limit agresivo.
• El cargo Stripe puede tardar ~1h en propagar.
• Solo un miembro por workspace puede suscribirse a Go.

3.3 Paquete npm del provider custom no instalado

"provider": {
  "deepseek": {
    "npm": "@ai-sdk/openai-compatible",
    ...
  }
}

El auto-install puede fallar silenciosamente (log: background dependency install failed).

Fix:

cd ~/.config/opencode && npm install @ai-sdk/openai-compatible

3.4 {env:VAR} no se resuelve desde el .env del config

En opencode ≥1.18, {env:VAR} solo se resuelve si la variable está exportada en el entorno del proceso — NO lee ~/.config/opencode/.env automáticamente. Resultado: peticiones sin header Authorization → Authentication Fails (governor).

Fix: exportar en ~/.bashrc:

export api_deepseek="$(grep -oP 'api_deepseek=\K\S+' ~/.config/opencode/.env)"
export api_groq="$(grep -oP 'api_groq=\K\S+' ~/.config/opencode/.env)"

4. Procedimiento de diagnóstico completo

# 1. Versión y binario
opencode --version; which -a opencode

# 2. Credenciales registradas
opencode auth list          # → ~/.local/share/opencode/auth.json

# 3. Catálogo de modelos (ojo: lista TODO aunque no tengas saldo)
opencode models | grep -E "^(opencode|opencode-go)/"

# 4. Log de errores (BUSCAR: database disk image is malformed)
tail -100 ~/.local/share/opencode/log/opencode.log

# 5. Estado de la DB
ls -la ~/.local/share/opencode/opencode.db*

# 6. Endpoints de los providers (models.dev)
curl -s https://models.dev/api.json | python3 -c "
import sys, json
d = json.load(sys.stdin)
for pid in ['opencode', 'opencode-go']:
    print(pid, '->', d[pid]['api'])"

# 7. Prueba directa del gateway Go (key real, max_tokens=1)
KEY=$(python3 -c "import json;print(json.load(open('$HOME/.local/share/opencode/auth.json'))['opencode-go']['key'])")
curl -s -X POST https://opencode.ai/zen/go/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":1}'

# 8. Captura de petición real (si el problema es de headers):
python3 scripts/dbg_proxy.py &
# config temporal con baseURL http://127.0.0.1:9999/v1 → revisar /tmp/proxy_capture.log

5. Verificación final

cd ~ && opencode run 'Respond with exactly: OK' 2>&1
# Esperado:
# > build · deepseek-v4-flash
# OK

Criterios:

• El modelo responde (no un error).
• Sin errores nuevos en ~/.local/share/opencode/log/opencode.log.
• opencode run --model opencode-go/deepseek-v4-flash 'hi' → responde.
• opencode run --model deepseek/deepseek-v4-flash 'hi' → responde (provider directo).

6. Archivos tocados

Archivo	Cambio
~/.local/share/opencode/opencode.db	Corrupta → respaldo + recreada
~/.config/opencode/opencode.jsonc	model/small_model → opencode-go/deepseek-v4-flash
~/.config/opencode/node_modules	npm install @ai-sdk/openai-compatible
~/.bashrc	exports de api_deepseek y api_groq

7. Lecciones

1. "Insufficient balance" no siempre significa que no pagaste — puede ser el catálogo equivocado (opencode/* Zen prepago vs opencode-go/* Go).
2. Los errores de cuenta del gateway son respuestas de estado, no de auth.
3. opencode models NO valida auth — lista el catálogo completo siempre.
4. La DB corrupta es el "falso muerto" de opencode: revisa el log antes de tocar proveedores.
5. El .env del config no se carga solo en opencode ≥1.18: exporta las vars.

---

8. Actualización 2026-08-02 — Error transitorio "Insufficient Balance"

Síntoma: en el TUI (con modelo OpenCode Go correcto) aparece de vez en cuando:

Upstream request failed: [invalid_request_error] Insufficient Balance

Diagnóstico: error TRANSITORIO del gateway de OpenCode, NO de tu cuenta.

• Ocurrió UNA sola vez en el log (grep -c "Insufficient Balance" ~/.local/share/opencode/log/opencode.log → 2 líneas = mismo evento).
• La misma sesión del TUI tuvo 7 requests exitosos antes con el mismo modelo.
• ~13 minutos después, todas las pruebas pasaban (curl gateway, opencode run normal, con --variant high, y con contexto de ~24K tokens).
• Formato invalid_request_error + "Insufficient Balance" capital B = estilo del proveedor upstream del gateway (blip interno), no el CreditsError de tu cuenta.

Cómo distinguir los DOS errores "Insufficient":

Error	Es de tu cuenta	Qué hacer
CreditsError: Insufficient balance. Manage your billing here: <URL> (b minúscula + URL)	✅ Sí	Verificar saldo Zen / suscripción del workspace
[invalid_request_error] Insufficient Balance (B mayúscula, sin URL)	❌ No	Reintentar; es transitorio

Si se repite con frecuencia:

1. Revisa el medidor de uso: consola → pestaña "Uso" (límite $12 por 5h — con DeepSeek V4 Flash estás lejísimos: ~$0.004/request de 24K tokens).
2. Activa "Use balance" en la pestaña Go de la consola y carga un saldo Zen pequeño (ej. $5) como red de seguridad: si el gateway falla el chequeo de suscripción, cobra del saldo en vez de bloquear.
3. Si persiste: reporta en https://github.com/anomalyco/opencode/issues con el timestamp del log (~/.local/share/opencode/log/opencode.log).

Suite de verificación "como humano" (todas deben pasar):

# 1. Gateway directo (cuesta ~0 con max_tokens=1)
curl -s -X POST https://opencode.ai/zen/go/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":1}'

# 2. Run normal
opencode run 'Respond with exactly: PRUEBA_OK'

# 3. Variant de razonamiento (como el TUI)
opencode run --variant high 'Respond with exactly: VARIANT_HIGH_OK'

# 4. Contexto grande (~24K tokens, como sesión real)
opencode run 'Responde SOLO con: OK. Ignora el archivo.' -f <archivo_grande>

---

Repositorio

Este repo incluye:

• README.md — este tutorial.
• SKILL.md — skill de Hermes Agent reutilizable (mismo contenido operativo).
• scripts/dbg_proxy.py — proxy de depuración para capturar peticiones HTTP.

Licencia MIT.