Troubleshooting
September 6, 2026 · View on GitHub
Troubleshooting
Start with /quota_status in OpenCode, or opencode-quota status from a terminal. Both show which config, providers, authentication, and local files OpenCode Quota found.
First checks
- Run
/quota_statusin OpenCode, oropencode-quota statusfrom a terminal. - Find the provider or feature that is failing.
- Follow the matching fix below.
- Restart OpenCode after changing config or authentication.
If every provider is missing, confirm OpenCode Quota is listed in opencode.jsonc or .json. For TUI commands and displays, also confirm it is listed in tui.jsonc or .json.
Common problems
| Problem | Try this |
|---|---|
| Slash commands are missing | Check the plugin entries above, then restart OpenCode. |
| TUI command results appear in the wrong place | Use tuiCommandDisplay: "inline" for normal messages or "dialog" for a popup. Home always uses a popup because there is no session transcript. |
/quota shows no providers | Run /quota_status or opencode-quota status, then check provider detection and authentication. |
| Sidebar is missing | Confirm the TUI plugin is installed and tuiSidebarPanel.enabled is true. |
| Compact line is missing | Confirm the TUI plugin is installed and tuiCompactStatus.enabled is true. If needed, check suppressWhenNativeProviderQuota. |
| Compact line appears on Home only | Set tuiCompactStatus.sessionPrompt to true. |
| TUI toast is missing | Check enableToast, showOnIdle, showOnQuestion, and showOnCompact. Toasts are not available in Web. |
| Token reports are empty | Start OpenCode once, then use a model so opencode.db contains usage. |
| Pricing looks old | Run /pricing_refresh. |
Web shows Failed to send command after correct output | The command already worked. Do not retry. This is a known OpenCode 1.18.2 notification problem; no model was called. |
Update safely
-
Close OpenCode.
-
Preview the update:
npx @slkiser/opencode-quota@latest update --dry-run -
Inspect both safe changes and manual findings. Do not paste credential values into command output or issue reports.
-
Apply the plan:
npx @slkiser/opencode-quota@latest update -
Restart OpenCode.
-
Run
/quota_statusin OpenCode, or runopencode-quota statusin a terminal.
The updater preserves unrelated settings, comments, and plugins where targeted editing is safe. Credential findings stay manual, and --yes authorizes only safe config/cache work. See Updating safely for the complete workflow.
| Update result | What to do |
|---|---|
| Obsolete OpenCode Go source | Configure OPENCODE_API_KEY, trusted global provider.opencode-go.options.apiKey, fallback provider.opencode.options.apiKey, or opencode auth login -p opencode-go. Verify it, then manually remove the reported old variable/file. Workspace/cookie material cannot become an API key. |
| Ambiguous OpenCode Zen environment names | Decide whether the names belong to Zen or OpenCode's workspace feature. If they are Zen credentials, create and protect the supported global opencode-quota/opencode.json manually. Never paste the values into output or reports. |
| Unsupported display migration | Fix the reported invalid, duplicate, or ambiguous config manually. Use root accountingDetail: "summary" or "detailed"; do not share the rejected value. |
| Update race or partial-write failure | No package cache was deleted. Read the error's exact changed-path list, inspect those files, fix the cause, and rerun update --dry-run for a fresh plan. Do not restore over concurrent edits blindly. |
Provider fixes
Custom providers
Run /quota_status and inspect quota_providers. Each definition shows its stable/provider IDs, mode, format or exact local state path, model coverage, live outcome, credential category, environment name, and safe checked paths. These results are fetched live for the status command; cached results are not substituted.
| Symptom | Fix |
|---|---|
| Config is rejected | Run opencode-quota provider add and keep quotaProviders in global OpenCode JSONC/JSON. Remove customSources, unknown fields, duplicate IDs/request identities, or overlapping model coverage. |
Definition is unavailable | Confirm OpenCode reports the exact configured providerId. With onlyCurrentModel, confirm the model id without provider prefix matches modelIds, or omit modelIds for provider-wide coverage. |
missing_credential | Set the explicit apiKeyEnv, or configure trusted global provider.<providerId>.options.apiKey, or a strict { "type": "api", "key": "..." } auth entry. |
http_error, timeout, or response error | Check the endpoint service and response format. /quota_status intentionally hides URLs, request/response contents, raw errors, and secret material. |
| One definition fails but others render | This is expected partial-aggregate behavior. Successful definitions remain visible and the failed definition stays an error/status row. |
| Single-window output shows fewer rows | Each source keeps only its lowest remaining percentage, or first value row. Use "formatStyle": "allWindows" for every row. |
| CLI/export looks stale | show --json and the export file are cache-only and never fetch providers. Trigger a normal TUI/background refresh first. /quota_status is the live diagnostic surface. |
Anthropic (Claude)
Run /quota_status and check the Anthropic section.
| Symptom | Fix |
|---|---|
claude not found | Install Claude Code and make sure claude is on your PATH. |
| Claude is installed at a custom path | Set anthropicBinaryPath in opencode-quota/quota-toast.json. |
| Not authenticated | Run claude auth login, then confirm claude auth status works. |
| Auth works but no quota rows appear | Check quota_source and message in /quota_status; re-authenticate Claude if the OAuth credential fallback is missing or stale. |
| Provider not detected | Confirm OpenCode is configured to use the anthropic provider. |
GitHub Copilot
Run /quota_status and check copilot_quota_auth, deployment, api_host, enterprise_host_source, billing_model, billing_scope, quota_api, budget_api, and token_compatibility_error.
| Symptom | Fix |
|---|---|
| OpenCode Copilot works but no personal quota row appears | Check oauth_accounting_state, deployment, and api_host; re-authenticate Copilot in OpenCode if the OAuth token or its stored GHE.com host is invalid. |
| Organization or enterprise accounting is missing | Create copilot-quota-token.json as described in GitHub Copilot setup. Public billing reports still need a separate billing credential. |
| GHE.com host is rejected | Use the enterprise hostname (for example acme.ghe.com) or a host-only HTTPS URL. Do not enter api., a path, query, fragment, port, userinfo, wildcard, HTTP URL, IP/localhost, or another domain. |
| Personal report is forbidden | Use a fine-grained PAT with Plan: read or a GitHub App user access token. A GitHub App installation token cannot query a personal report. |
| Organization report or budget is forbidden | Use an organization admin/billing-manager credential. Fine-grained PAT and GitHub App credentials need Organization administration: read. Usage can still appear with a budget warning when only budget access fails. |
| Enterprise report is forbidden | Use a classic PAT held by an enterprise admin or billing manager. GitHub does not support fine-grained PATs or GitHub App access tokens for enterprise billing reports. |
| Usage appears without a percentage | This is expected when GitHub supplies usage but no real allowance or positive budget denominator. opencode-quota does not invent a percentage. |
| Legacy PRU config is rejected | Set "billingModel": "legacy_premium_requests" only for an existing annual Copilot Pro or Pro+ plan that remained on legacy billing after June 1, 2026. |
| Rate-limit error | Wait for GitHub's REST API rate limit to reset, then run /quota again. |
OpenAI
Run /quota_status and check the OpenAI auth source and token status.
| Symptom | Fix |
|---|---|
| OpenAI quota missing | Confirm OpenCode native OpenAI OAuth is present in auth.json. |
| Token expired | Re-run OpenCode's OpenAI auth flow. |
| Provider not detected | Confirm your OpenCode config uses the openai provider or a compatible OpenAI auth entry. |
Cursor
Run /quota_status and check the Cursor section.
| Symptom | Fix |
|---|---|
| Cursor not detected | Put @playwo/opencode-cursor-oauth before @slkiser/opencode-quota in opencode.json. |
| Cursor auth missing | Run opencode auth login --provider cursor. |
| Quota appears but no remaining percentage | Set cursorPlan or cursorIncludedApiUsd in opencode-quota/quota-toast.json. |
| Billing cycle looks wrong | Set cursorBillingCycleStartDay in opencode-quota/quota-toast.json to your local billing anchor day. |
| Unknown Cursor pricing | Run /pricing_refresh; if still unknown, check /quota_status for unknown model ids. |
Qwen Code
Run /quota_status and check qwen_oauth_source, qwen_local_plan, and the qwen_code live probe section.
| Symptom | Fix |
|---|---|
| Qwen not detected | Put opencode-qwencode-auth before @slkiser/opencode-quota in opencode.json. |
| Auth missing | Complete the Qwen companion plugin auth flow. |
| Counters do not move | Confirm the current model is qwen-code/*; Qwen quota is local request estimation for matching model usage. |
| Usage looks stale | Check the local state file path shown by /quota_status. |
Alibaba Coding Plan
Run /quota_status and check the Alibaba auth, resolved tier, state-file path, and alibaba_coding_plan live probe section.
| Symptom | Fix |
|---|---|
| API key not detected | Use ALIBABA_CODING_PLAN_API_KEY, ALIBABA_API_KEY, trusted user/global OpenCode config, or OpenCode auth. Repo-local provider secrets are ignored. |
| Limits need tuning | Run opencode-quota provider add, choose local estimate, and use the maintained alibaba-coding-plan id with its five-hour, weekly, and monthly rolling windows. |
| Counters do not move | Confirm the current model is alibaba/* or alibaba-cn/*. |
| Quota seems stale | Check the state-file path shown in /quota_status. |
MiniMax, Kimi, Chutes AI, Synthetic, Z.ai, Zhipu, NanoGPT, and DeepSeek
These providers use trusted env vars, trusted user/global OpenCode config, or native OpenCode auth. Run /quota_status and check the provider-specific API-key diagnostics.
| Provider | Useful checks |
|---|---|
| MiniMax Token Plan | Use MINIMAX_CODING_PLAN_API_KEY or MINIMAX_API_KEY for the international endpoint. Runtime/config ids like minimax and minimax-coding-plan use this provider. Repo-local provider secrets are ignored. |
| MiniMax Token Plan (CN) | Use MINIMAX_CHINA_CODING_PLAN_API_KEY or trusted user/global OpenCode config under minimax-china-coding-plan, minimax-cn-coding-plan, minimax-cn, or minimax-china. Runtime id minimax-cn-coding-plan uses this provider. |
| Kimi Code | Use KIMI_API_KEY or KIMI_CODE_API_KEY; repo-local provider secrets are ignored. |
| Chutes AI | Use CHUTES_API_KEY, trusted user/global config, or OpenCode auth. |
| Synthetic | Use SYNTHETIC_API_KEY, trusted user/global config, or OpenCode auth. |
| Z.ai Coding Plan | Use ZAI_API_KEY or ZAI_CODING_PLAN_API_KEY; malformed fallback auth is surfaced as an auth error. |
| Zhipu Coding Plan | Use ZHIPU_API_KEY or ZHIPU_CODING_PLAN_API_KEY; malformed fallback auth is surfaced as an auth error. |
| NanoGPT | Use NANOGPT_API_KEY, NANO_GPT_API_KEY, trusted user/global config, or OpenCode auth. |
| DeepSeek | Use DEEPSEEK_API_KEY, trusted user/global config under provider.deepseek.options.apiKey, or OpenCode auth. This provider shows balance only because DeepSeek does not expose a quota reset window. |
For security, repo-local opencode.json / opencode.jsonc is ignored for provider secrets in these integrations. Put secrets in environment variables or trusted user/global config. OpenCode auth fallbacks for API-key providers require { "type": "api", "key": "..." } entries.
Google Antigravity
Run /quota_status and check the google_antigravity section. The toast diagnostics also show the effective googleModels value and googleModels_source (default or the configuration file path).
| Symptom | Fix |
|---|---|
| Companion missing | Put opencode-antigravity-auth before @slkiser/opencode-quota in opencode.json. |
| Accounts not found | Check the selected antigravity-accounts.json path shown by /quota_status. |
| Refresh tokens invalid | Re-authenticate with the companion plugin. |
| Provider returns no rows | Check live_probe, live_entry_*, and live_error_* in /quota_status. |
Google AGY
Run /quota_status and check the google_agy section.
| Symptom | Fix |
|---|---|
| Companion missing | Put @anthonyhaussman/opencode-agy-auth before @slkiser/opencode-quota in opencode.json. |
| Provider not enabled in manual mode | Include google-agy in enabledProviders in opencode-quota/quota-toast.json. |
| Auth missing | Run opencode auth login --provider google-agy. |
| Project missing | Set OPENCODE_AGY_PROJECT_ID or provider.google-agy.options.projectId. |
| Provider returns no rows | Check live_probe, live_entry_*, and live_error_* in /quota_status. |
Gemini CLI (deprecated)
This section is only for repairing an existing setup. Gemini CLI quota support is deprecated in v4.1 and planned for removal in v5.0.0. Existing configuration and authentication continue to work; OpenCode Quota does not switch either one automatically. For new choices, see Gemini CLI in the provider guide.
Run /quota_status and check the Gemini CLI live probe rows.
| Symptom | Fix |
|---|---|
| Companion missing | Put opencode-gemini-auth before @slkiser/opencode-quota in opencode.json. |
| Provider not enabled in manual mode | Include google-gemini-cli in enabledProviders in opencode-quota/quota-toast.json. |
| Auth missing | Run opencode auth login --provider google. |
| Project missing | Set provider.google.options.projectId, OPENCODE_GEMINI_PROJECT_ID, GOOGLE_CLOUD_PROJECT, or GOOGLE_CLOUD_PROJECT_ID. |
Xiaomi MiMo
Run /quota_status and check the xiaomi section. Diagnostics show state, source, checked paths, and safe live summaries, never cookie names, cookie values, or raw responses.
| Symptom | Fix |
|---|---|
| Config not detected | Set MIMO_USAGE_COOKIE or create trusted user/global opencode-quota/mimo.json, then rerun /quota_status. |
| Config is invalid | Fix or remove the reported higher-priority source; invalid sources intentionally block fallback. |
| Provider not enabled in manual mode | Include canonical xiaomi in enabledProviders. |
| Monthly quota missing | Confirm the plan is active and check live_error_*; explicitly expired plans are hidden. |
| Balance or plan details missing | Check the partial live summary. Usage, detail, and balance requests fail independently, so other available rows can still appear. |
| Per-key costs missing | Per-API-key cost accounting is not supported until Xiaomi provides endpoint and schema evidence. |
| Session expired | Sign in again at platform.xiaomimimo.com, manually copy a fresh request Cookie header, and update the same trusted credential source. |
OpenCode Go
Run /quota_status and check the opencode_go section. It reports safe auth_* diagnostics, the selected display windows, normalized API usage, and live_fetch_error without exposing the API key.
| Symptom | Fix |
|---|---|
| Provider not detected | Set OPENCODE_API_KEY, trusted global provider.opencode-go.options.apiKey, fallback provider.opencode.options.apiKey, a strict opencode-go API-key entry in OpenCode auth.json, or a strict legacy opencode auth entry as the final fallback. Then check auth_state, auth_source, and auth_checked_paths. |
auth_state is invalid | Fix the primary opencode-go record in auth.json so it is { "type": "api", "key": "..." }. A malformed primary record blocks the legacy opencode fallback and is reported in auth_error. |
| API returns 401 or 403 | The usage API rejected the key. Update the winning source shown by auth_source, wait briefly for credential caching to expire, and rerun /quota_status. |
| Invalid API response | Check live_fetch_error. OpenCode Quota requires valid 5h, Weekly, and Monthly results, so one missing or malformed API window rejects the full response instead of showing partial quota. |
| API request times out or fails | Check live_fetch_error, confirm https://opencode.ai/zen/go/v1/usage is reachable, and retry. Increase requestTimeoutMs only when the error is a timeout. |
| Expected window is not displayed | Check selected_windows, then update opencodeGoWindows in opencode-quota/quota-toast.json. This setting only filters the already validated 5h (rolling), Weekly (weekly), and Monthly (monthly) API results. |
| Provider missing in manual mode | Include opencode-go in enabledProviders in opencode-quota/quota-toast.json. |
Token reports
Run /quota_status and check pricing snapshot health plus OpenCode database paths.
| Symptom | Fix |
|---|---|
/tokens_* is empty | Start OpenCode once so it creates opencode.db, then run a session with model usage. |
| Pricing looks stale | Run /pricing_refresh. |
| Runtime pricing does not change output | Check pricingSnapshot.source in opencode-quota/quota-toast.json; bundled keeps packaged pricing active. |
| Cursor model has unknown pricing | Run /pricing_refresh; Cursor auto and composer* use bundled deterministic pricing. |