Skip to content

troubleshooting.md

Latest commit

 

History

History
851 lines (642 loc) · 27.9 KB

troubleshooting.md

File metadata and controls

851 lines (642 loc) · 27.9 KB
Raw

Troubleshooting

Common setup, authentication, model, and request-debugging issues for oc-codex-multi-auth (current package line, including the 24-tool surface and GPT-5.6 catalog).

For install modes, the full tool list (with args), and standalone CLI commands (doctor, status, list, limits, health, diag, warm), see Tools and CLI and Getting Started. For advanced env vars (CODEX_THREAD_ID, OPENCODE_CODEX_PROMPT_URL, etc.) see Configuration.

Quick Reset: Most issues can be resolved by deleting ~/.opencode/auth/openai.json and running opencode auth login again.

If you prefer guided recovery before manual debugging, run:

codex-setup
codex-doctor
codex-doctor fix=true
codex-next

Or without an agent loop (no model tokens):

oc-codex-multi-auth doctor
oc-codex-multi-auth status --json
oc-codex-multi-auth warm

For machine-readable automation or CI checks, these read-only tools also accept format="json":

codex-status format="json"
codex-limits format="json"
codex-health format="json"
codex-next format="json"
codex-list format="json"
codex-dashboard format="json"
codex-metrics format="json"
codex-doctor deep=true format="json"

Known Limitations

✅ RESOLVED: OpenCode plugin blocking (v4.9.0+)

Status: Fixed in v4.9.0 by renaming the package.

What was happening:

OpenCode's plugin loader explicitly skips plugins with opencode-openai-codex-auth in the name:

if (plugin.includes("opencode-openai-codex-auth") || plugin.includes("opencode-copilot-auth")) continue

Resolution:

This package previously shipped under older names. oc-codex-multi-auth is the supported package line.

If you were using the old package:

Update your ~/.config/opencode/opencode.json:

{
  "plugin": ["oc-codex-multi-auth"]
}

Tracking: Issue #11

Installation & Loading Issues

Plugin not downloading / no logs

Symptoms:

  • Plugin folder missing under ~/.cache/opencode/node_modules/
  • No files in ~/.opencode/logs/codex-plugin/ even with logging enabled

Checks:

  1. Verify config path and plugin list:
    • Global: ~/.config/opencode/opencode.json
    • Project: ./.opencode.json
    • Entry should include: "plugin": ["oc-codex-multi-auth"]
  2. Confirm plugin cache location (npm plugins are cached, not stored in ~/.opencode/plugins/): 
    ls ~/.cache/opencode/node_modules/oc-codex-multi-auth
  3. Remember: request logs only appear after the first OpenAI request: 
    ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.5 --variant=medium
  4. Check registry access: 
    npm view oc-codex-multi-auth version
  5. If the plugin is present but still won’t load, rerun npx -y oc-codex-multi-auth@latest so the installer refreshes the config and clears OpenCode's cached plugin copy.

Performance & Latency

Slow first response / startup latency

What’s normal:

  • The first request may fetch Codex instructions and/or the OpenCode codex prompt from GitHub (catalog + prompt caches under ~/.opencode/cache/).
  • Default requestTransformMode is native. Startup prewarm of prompt caches only runs when legacy transform is enabled (CODEX_AUTH_REQUEST_TRANSFORM_MODE=legacy or config requestTransformMode: "legacy") and is not disabled with CODEX_AUTH_PREWARM=0.

Tuning knobs:

  1. Disable prewarm when using legacy transform (if you prefer zero background fetches at startup): 
    CODEX_AUTH_PREWARM=0 opencode
  2. Enable fast-session mode (recommended: hybrid) to speed up trivial/interactive turns without changing defaults for complex prompts: 
    // ~/.opencode/openai-codex-auth-config.json
{
  "fastSession": true,
  "fastSessionStrategy": "hybrid",
  "fastSessionMaxInputItems": 24
}
    Or via env: 
    CODEX_AUTH_FAST_SESSION=1 opencode

Note: fastSessionStrategy: "always" forces fast tuning even on complex prompts and can reduce depth. Use hybrid unless you explicitly want maximum speed.

Concurrent Sessions & Storage

codex-pool reports that plugin configuration is locked

Symptoms:

  • A pool mutation reports config_locked with retryable: true in JSON output.
  • Text output says the plugin configuration is locked by another process and no change was made.

Cause: Another OpenCode process is updating ~/.opencode/openai-codex-auth-config.json. Pool dry-runs do not acquire this lock. Every non-dry mutation, including a possible no-op, waits for the bounded retry window and is revalidated under the lock so its result cannot rely on a stale preview.

Solution: No partial change was applied. Retry the same codex-pool action shortly. If contention persists, finish or stop other processes that are actively changing plugin configuration, then retry.

Multi-worktree collision detected on account storage warning

This advisory warning means another live process or host is using the same account-storage file. It includes the foreign and local PID, host, and working directory so you can identify the sessions. The JSON worktree lock remains advisory, while account mutations and OAuth refreshes use a separate enforced transaction lease. On one host with a local filesystem, parallel sessions serialize refresh exchange and commit instead of reusing or clobbering a single-use token. Repeated warnings are throttled to once per minute for each storage path and foreign lock generation.

If account rotation or rate-limit state appears stale, ensure each worktree resolves to the intended project storage, then restart OpenCode and inspect the account list. Do not delete a lock belonging to a live process. Cross-host and network-filesystem coordination are not provided by the local transaction lease.

Authentication Issues

401 Unauthorized Error

Symptoms:

Error: 401 Unauthorized
Failed to access Codex API

Causes:

  1. Token expired
  2. Not authenticated yet
  3. Invalid credentials
  4. Stored OAuth grant is missing the connector scopes required by the current Codex auth flow

Solutions:

  1. Re-authenticate:

    opencode auth login

    Re-auth is required for accounts whose recorded OAuth scope is explicitly missing one of openid, profile, email, or offline_access; those records are marked inactive until they are refreshed through login. Accounts with no recorded scope stay active, and any account marked inactive by this check is restored automatically once a complete scope is known.

  2. Check auth file exists:

    cat ~/.opencode/auth/openai.json
# Should show OAuth credentials

  3. Check token expiration:

    cat ~/.opencode/auth/openai.json | jq '.expires'
date +%s000  # Compare to current timestamp

  4. Collect diagnostics from the error payload:

    • Newer versions include diagnostics on 401 responses (for example requestId and cfRay).
    • Share those IDs when filing an issue so upstream auth failures are easier to trace.
Browser Doesn't Open for OAuth

Symptoms:

  • opencode auth login succeeds but no browser window
  • OAuth callback times out

Solutions:

  1. Manual URL paste:

    • Re-run opencode auth login
    • Select "Codex OAuth (Device Code)" first if you are on SSH, WSL, or a headless machine
    • If device code is unavailable, fall back to "Codex OAuth (Manual URL Paste)"
    • Paste the full redirect URL after login when using the manual flow

  2. Check port 1455 availability:

    # macOS/Linux
lsof -i :1455

# Windows
netstat -ano | findstr :1455

  3. Stop Codex CLI if running — both use port 1455

Authorization Session Expired

Symptoms:

  • Browser shows: Your authorization session was not initialized or has expired

Solutions:

  • Re-run opencode auth login to generate a fresh URL
  • Open the URL directly in browser (don't use a stale link)
  • For SSH/WSL/remote, use "Device Code" first, then "Manual URL Paste" if needed
403 Forbidden Error

Cause: ChatGPT subscription issue

Check:

  1. Active ChatGPT Plus or Pro subscription
  2. Subscription not expired
  3. Billing is current

Solution: Visit ChatGPT and verify subscription status

"Usage not included in your plan"

Symptoms:

  • Requests fail with: Usage not included in your plan
  • Often reported on Business/Team workspaces

Cause: The plugin is using the wrong workspace/account id (personal vs business).

Solutions:

  1. Upgrade to the current release of oc-codex-multi-auth (workspace routing logic was hardened for Business + Personal dual accounts in the 5.x line and renamed in 6.0.0).
  2. Re-run opencode auth login and select the correct workspace when prompted.
  3. If running non-interactively, set CODEX_AUTH_ACCOUNT_ID to the workspace account id and re-login.
  4. Verify the workspace has Codex access in the ChatGPT UI.
Two members of one Business workspace consume the same quota

Symptoms:

  • Two different emails belong to the same ChatGPT Business workspace.
  • Both entries have the same chatgpt-account-id and switching entries keeps consuming the quota of whichever member logged in last.
  • codex-health reports a Business member credential conflict.

Cause: A Business workspace id identifies the subscription, not an individual seat. Older builds could match the host OAuth fallback by that shared id and replace every matching entry with the last member's token.

Solution: Upgrade to a build with member-aware account identity, then remove the affected entries and run opencode auth login once for each member. Make sure the browser is signed in as the intended member for each login. The plugin stores the token's chatgpt_account_user_id, so each entry keeps its own bearer token and /wham/usage reads the corresponding seat quota. Already-overwritten credentials cannot be reconstructed and require re-login.

Two workspace subscriptions report the same plan and quota

Symptoms:

  • One ChatGPT login (one email / Apple ID) holding two workspace subscriptions - for example Team and Plus.
  • codex-limits reports the same plan and the same percentage for every entry.
  • codex-switch to the other account keeps draining the same pool.
  • Logging in again under the other workspace appears to overwrite every entry.

Cause: The OAuth flow requests id_token_add_organizations=true, so the id_token lists every organization the login belongs to. Releases before this fix persisted one account entry per organization, but all of those entries shared the login's single OAuth token. The Codex backend meters quota by the chatgpt-account-id header and ignores organization ids, so an entry whose id was an organization id silently fell back to the token's default subscription - N entries, one pool.

Each workspace subscription is a distinct ChatGPT account with its own chatgpt_account_id claim, so separate tokens are what produce separate quotas.

Solutions:

  1. Upgrade to a release containing this fix. One opencode auth login now persists exactly one account, bound to the token's ChatGPT account id and labelled with the workspace you selected.
  2. Log in once per workspace: run opencode auth login, pick the first workspace, then run it again and pick the second. Each login appends a separate account carrying its own token, so codex-limits reports the two subscriptions independently.
  3. Existing entries are not rewritten. Accounts persisted by an older release keep their stored organization id. Requests for them are now redirected to the token's ChatGPT account id so they reach a real pool instead of being silently mis-billed, but duplicate rows left over from the old one-entry-per-organization behaviour remain until you remove them. For a clean pool, re-run opencode auth login, choose the fresh (not add) login mode, then add the second workspace.
"All N account(s) failed (server errors or auth issues)"

Symptoms:

  • Request loop ends with All 14 account(s) failed ... (count varies)
  • Frequent retries, then hard failure

Common causes:

  1. Most accounts in the pool have expired/invalid refresh tokens
  2. Account pool contains duplicate stale accounts
  3. Temporary upstream/server failures across all available accounts

Solutions:

  1. Re-auth at least one known-good account first: 
    opencode auth login
  2. Check account storage health (global and project-scoped):
    • ~/.opencode/oc-codex-multi-auth-accounts.json
    • ~/.opencode/projects/<project-key>/oc-codex-multi-auth-accounts.json
    • ~/.opencode/oc-codex-multi-auth-flagged-accounts.json
  3. Remove obviously stale/duplicate entries and keep only verified accounts.
  4. Re-run with logging and inspect per-account failures: 
    DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "ping" --model=openai/gpt-5-codex
  5. If you only need personal Plus/Pro usage, ensure login selected the intended personal workspace/account id.
  6. Run guided diagnostics and safe auto-remediation: 
    codex-doctor
codex-doctor fix=true
  7. If you are onboarding or returning after a long gap, run: 
    codex-setup
codex-setup wizard=true
codex-next


</details>

---

## Model Issues

<details open>
<summary><b>Model Not Found</b></summary>

**Error:** `Model 'openai/gpt-5-codex-low' not found`

**Cause 1: Config key mismatch**

Check your config:
```json
{
  "models": {
    "gpt-5-codex-low": { ... }  // ← This is the key
  }
}

CLI must match exactly:

opencode run "test" --model=openai/gpt-5-codex-low  # Must match config key

Cause 2: Missing provider prefix

Wrong Correct
--model=gpt-5-codex-low --model=openai/gpt-5-codex-low

Note: opencode models openai currently shows only OpenCode's built-in provider catalog. If you add template-defined or custom models, use opencode debug config to confirm they were merged into the effective config.

Selector note: a compact modern (--modern) install exposes base OAuth families with the --variant presets. The default install writes no catalog, so if a selector below is missing, reinstall with --modern. Prefer:

opencode run "test" --model=openai/gpt-5.5 --variant=medium

Use explicit IDs such as openai/gpt-5.5-medium only after installing with --full or --legacy. If a host build rejects the bare base entry even when opencode debug config shows it, reinstall with --full rather than assuming medium IDs exist on a compact install.

Per-Model Options Not Applied

Symptom: All models behave the same despite different reasoningEffort

Debug:

DEBUG_CODEX_PLUGIN=1 opencode run "test" --model=openai/your-model

Look for:

hasModelSpecificConfig: true  ← Should be true
resolvedConfig: { reasoningEffort: 'low', ... }  ← Should show your options

Common causes:

  1. Model name in CLI doesn't match config key
  2. Typo in config file
  3. Wrong config file location
"Model is not supported when using Codex with a ChatGPT account"

Symptoms:

  • Request fails with an entitlement-style 400/403 mentioning model support for ChatGPT Codex OAuth
  • Common after switching workspaces or selecting a model your workspace is not currently entitled to

Cause: The selected model is currently not entitled for the active ChatGPT account/workspace.

Solutions:

  1. Re-auth/login to refresh workspace selection: 
    opencode auth login
  2. Add another entitled account/workspace. The plugin tries remaining accounts/workspaces before model fallback.
  3. Model works in the Codex CLI/TUI or plain opencode but not through this plugin (typically the newest preview tier, e.g. gpt-5.6-sol): the backend evaluates model entitlement per client identity (originator + User-Agent). The plugin defaults GPT-5.6 tiers to the host identity (originator: opencode, the one plain opencode passes sol with) and everything else to the Codex CLI identity (codex_cli_rs/<version>; the backend gates those tiers on the catalog's minimal_client_version, read from the UA). By default it does not pin openai-organization (upstream clients don't send it; workspace routing is carried by chatgpt-account-id). Escape hatches: 
    CODEX_AUTH_CLIENT_IDENTITY=codex opencode        # force the Codex CLI identity for all models
CODEX_AUTH_CLIENT_IDENTITY=opencode opencode     # force the host identity for all models
CODEX_AUTH_DISABLE_CODEX_USER_AGENT=1 opencode   # keep the host runtime's User-Agent
CODEX_AUTH_CLIENT_VERSION=0.150.0 opencode       # advertise a different Codex CLI version
CODEX_AUTH_HOST_VERSION=1.18.0 opencode          # advertise a different opencode version
CODEX_AUTH_SEND_ORGANIZATION_HEADER=1 opencode   # restore legacy openai-organization pinning
    If the model still fails only through the plugin, run codex-health and compare the failing pooled account ids against the account the Codex CLI uses (~/.codex/auth.json).
  4. Default public selectors that are commonly entitlement-gated can auto-fallback: the GPT-5.6 preview tiers (gpt-5.6-sol/gpt-5.6-terra/gpt-5.6-luna) degrade down the tier chain to gpt-5.5, and gpt-5.5/canonical gpt-5-codex degrade through gpt-5.4, gpt-5.4-mini, then gpt-5.4-nano.
  5. Enable fallback policy if you also want automatic downgrades for manual/legacy selectors: 
    CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback opencode
  6. Default fallback chain (auto-fallback for the 5.6 tiers and gpt-5.5/gpt-5-codex; full chain when policy is fallback and not overridden):
    • gpt-5.6-sol -> gpt-5.6-terra -> gpt-5.6-luna -> gpt-5.5 (then the gpt-5.5 chain below)
    • gpt-5.5 -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano
    • gpt-5-codex -> gpt-5.4 -> gpt-5.4-mini -> gpt-5.4-nano
    • gpt-5.4-pro -> gpt-5.4 (if gpt-5.4-pro is selected manually)
    • gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex
    • gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex (if Spark IDs are selected manually)
    • gpt-5.2-codex -> gpt-5-codex
    • gpt-5.1-codex -> gpt-5-codex
  7. Configure a custom fallback chain in ~/.opencode/openai-codex-auth-config.json: 
    {
"unsupportedCodexPolicy": "fallback",
"fallbackOnUnsupportedCodexModel": true,
"unsupportedCodexFallbackChain": {
   "gpt-5.5": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
   "gpt-5.4": ["gpt-5.4-mini", "gpt-5.4-nano"],
   "gpt-5.4-pro": ["gpt-5.4"],
   "gpt-5-codex": ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"],
   "gpt-5.3-codex": ["gpt-5-codex", "gpt-5.2-codex"],
    "gpt-5.3-codex-spark": ["gpt-5-codex", "gpt-5.3-codex", "gpt-5.2-codex"]
  }
}
  8. Use strict mode for explicit entitlement failures outside the default public selector auto-fallbacks: 
    CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=strict opencode
  9. Disable default-selector auto-fallbacks when you need strict entitlement failures for those selectors: 
    CODEX_AUTH_DISABLE_GPT56_AUTO_FALLBACK=1 opencode
CODEX_AUTH_DISABLE_GPT55_AUTO_FALLBACK=1 opencode
CODEX_AUTH_DISABLE_CODEX_AUTO_FALLBACK=1 opencode
    Each variable only disables its own automatic default-selector fallback path (GPT56 covers all three 5.6 tiers); explicit unsupportedCodexPolicy: "fallback" chains still apply.
  10. Legacy compatibility toggle (only controls gpt-5.3-codex -> gpt-5.2-codex):
CODEX_AUTH_FALLBACK_GPT53_TO_GPT52=0 opencode
  1. Legacy generic fallback toggle compatibility:
CODEX_AUTH_FALLBACK_UNSUPPORTED_MODEL=1 opencode
  1. Verify effective upstream model when debugging Spark/fallback behavior:
ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "ping" --model=openai/gpt-5.3-codex-spark

Then inspect ~/.opencode/logs/codex-plugin/request-*-after-transform.json (.body.model). The TUI can keep showing the selected label while fallback is applied internally.

Multi-Turn Issues

Item Not Found Errors

Error:

AI_APICallError: Item with id 'msg_abc123' not found.
Items are not persisted when `store` is set to false.

Cause: Old plugin version (fixed in v2.1.2+)

Solution:

npx -y oc-codex-multi-auth@latest
opencode

Verify fix:

DEBUG_CODEX_PLUGIN=1 opencode
> write test.txt
> read test.txt
> what did you write?

Should see: Successfully removed all X message IDs

Context Not Preserved

Symptom: Model doesn't remember previous turns

Check logs:

ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode
> first message
> second message

Verify:

cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '.body.input | length'
# Should show increasing count (3, 5, 7, 9, ...)

What to check:

  1. Full message history present (not just current turn)
  2. No item_reference items (filtered out)
  3. All IDs stripped

Request Errors

400 Bad Request

Debug:

ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test"
cat ~/.opencode/logs/codex-plugin/request-*-error-response.json

Common causes:

  1. Invalid options for model (e.g., minimal for gpt-5-codex)
  2. Malformed request body
  3. Unsupported parameter
Rate Limit Exceeded

Error:

Rate limit reached for gpt-5-codex

Solutions:

  1. Wait for reset:

    cat ~/.opencode/logs/codex-plugin/request-*-response.json | jq '.headers["x-codex-primary-reset-after-seconds"]'

  2. Add more accounts:

    opencode auth login  # Add another account

  3. Switch model family:

    opencode run "task" --model=openai/gpt-5.1
Context Window Exceeded

Error:

Your input exceeds the context window

Solutions:

  1. Exit and restart OpenCode (clears history)
  2. Use compact mode (if OpenCode supports it)
  3. Switch to model with larger context
Account command says "Missing account number"

Symptoms:

  • codex-switch, codex-label, or codex-remove returns a missing index message
  • You expected an interactive picker

Cause: Interactive pickers require an interactive TTY session. In non-interactive sessions, you must pass index.

Solutions:

  1. Pass explicit index arguments: 
    codex-switch index=2
codex-label index=2 label="Work"
codex-remove index=2 confirm=true
  2. Run from an interactive terminal when you want picker menus.
  3. Use codex-list first to inspect valid index range.
Import concerns: accidental overwrite or bad backup file

Recommended safe flow:

  1. Preview first: 
    codex-import path="~/backup/accounts.json" dryRun=true
  2. Apply only after preview: 
    codex-import path="~/backup/accounts.json"
  3. Before apply, the plugin creates a timestamped pre-import backup when existing accounts are present.
  4. Use codex-export with no path to create timestamped backups in the storage-adjacent backups/ directory.

OAuth Callback Issues

Safari OAuth Callback Fails (macOS)

Symptoms:

  • "fail to authorize" after successful login
  • Safari shows "Safari can't open the page"

Cause: Safari's "HTTPS-Only Mode" blocks http://localhost callback.

Solutions:

  1. Use Chrome or Firefox (easiest)

  2. Disable HTTPS-Only Mode temporarily:

    • Safari > Settings (⌘,) > Privacy
    • Uncheck "Enable HTTPS-Only Mode"
    • Run opencode auth login
    • Re-enable after authentication
Port Conflict (Address Already in Use)

macOS / Linux:

lsof -i :1455
kill -9 <PID>
opencode auth login

Windows (PowerShell):

netstat -ano | findstr :1455
taskkill /PID <PID> /F
opencode auth login
Docker / WSL2 / Remote Development

OAuth callback requires browser to reach localhost on the machine running OpenCode. The plugin listens on both 127.0.0.1:1455 and [::1]:1455 so Windows/macOS/Linux dual-stack localhost resolution can complete the redirect.

WSL2:

  • Use VS Code's port forwarding, or
  • Configure Windows → WSL port forwarding

SSH / Remote:

ssh -L 1455:localhost:1455 user@remote

Docker / Containers:

  • OAuth with localhost redirect doesn't work in containers
  • Use Device Code first, then SSH port forwarding or manual URL flow if needed

Debug Techniques

Enable Full Logging 
DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "test"

What you get:

  • Console: Debug messages showing config resolution
  • Files: Request/response metadata logs
  • Files: Raw payloads included because CODEX_PLUGIN_LOG_BODIES=1 is set (sensitive)

Log locations:

  • ~/.opencode/logs/codex-plugin/request-*-before-transform.json
  • ~/.opencode/logs/codex-plugin/request-*-after-transform.json
  • ~/.opencode/logs/codex-plugin/request-*-response.json
Inspect Actual API Requests 
ENABLE_PLUGIN_REQUEST_LOGGING=1 CODEX_PLUGIN_LOG_BODIES=1 opencode run "test" --model=openai/gpt-5.5 --variant=medium

cat ~/.opencode/logs/codex-plugin/request-*-after-transform.json | jq '{
  model: .body.model,
  reasoning: .body.reasoning,
  text: .body.text,
  store: .body.store,
  include: .body.include
}'

Verify:

  • model: Normalized correctly?
  • reasoning.effort: Matches your config?
  • store: Should be false
  • include: Should have reasoning.encrypted_content

Getting Help

Before Opening an Issue

  1. Enable logging:

    DEBUG_CODEX_PLUGIN=1 ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "your command"

  2. Collect info:

    • OpenCode version: opencode --version
    • Plugin version: Check package.json or npm
    • Error logs from ~/.opencode/logs/codex-plugin/
    • Config file (redact sensitive info)

  3. Check existing issues: GitHub Issues

Reporting Bugs

Include:

  • Error message
  • Steps to reproduce
  • Config file (redacted)
  • Log files
  • OpenCode version
  • Plugin version

Account or Subscription Issues

Issue Solution
Auth problems Verify subscription at ChatGPT Settings
Free tier Not supported — requires Plus or Pro
Usage limits Check subscription limits
Account flagged Contact OpenAI support

To revoke and re-authorize:

  1. Revoke: ChatGPT Settings → Authorized Apps
  2. Remove tokens: opencode auth logout
  3. Re-authenticate: opencode auth login

Next: Configuration Guide | Architecture | Back to Home