To troubleshoot common OpenCode issues, start with the two things OpenCode itself recommends: check logs and check local storage. OpenCode writes timestamped logs to a local directory (on macOS/Linux under ~/.local/share/opencode/log/, and on Windows accessible via WIN+R with %USERPROFILE%\.local\share\opencode\log). When something “mysteriously” breaks—OpenCode won’t start, auth fails, a model can’t be selected, the desktop app shows a blank window—those logs usually tell you what failed (plugin load, provider init, network error, corrupted cache). If you need more detail, OpenCode supports increasing verbosity via opencode --log-level DEBUG, which is often the difference between guessing and knowing.
Once you have logs, the next step is to understand what local state might be involved. OpenCode stores session data and application data under ~/.local/share/opencode/ (or %USERPROFILE%\.local\share\opencode on Windows). That directory includes auth.json (credentials such as API keys or OAuth tokens), log/ (the logs you just checked), and project/ (project-specific session/message storage). Many “it used to work yesterday” problems come down to either corrupted state or a mismatched configuration: invalid provider credentials, stale provider packages, or a bad opencode.json(c) change. A classic example is “Model not available” or ProviderModelNotFoundError: OpenCode expects model identifiers in the form <providerId>/<modelId>, so a typo or an outdated model name in your config can block selection even if your account is fine. Another common one is ProviderInitError, which often indicates invalid or corrupted configuration; OpenCode’s own guidance is to verify provider setup, and if it persists, clear stored configuration/state and re-authenticate via /connect.
Desktop app issues have a few extra failure modes because the desktop UI runs alongside a local server sidecar. The OpenCode docs call out three frequent culprits: misbehaving plugins, a corrupted cache, or a bad server setting. The practical flow is: fully quit and relaunch; if the UI is unstable, disable plugins by removing or emptying the plugin key in your global config (for example ~/.config/opencode/opencode.jsonc on macOS/Linux or %USERPROFILE%\.config\opencode\opencode.jsonc on Windows); if installs are stuck or behavior is weird, clear the cache at ~/.cache/opencode (Windows: %USERPROFILE%\.cache\opencode) so OpenCode can rebuild it. If you see connection errors, check whether you configured a custom server URL or set environment variables like OPENCODE_PORT that force the desktop app onto a port that’s already taken. On Windows specifically, there’s a very common “blank window / won’t start” fix: install or update Microsoft Edge WebView2 Runtime, because OpenCode Desktop depends on it. And if you’re doing serious engineering work (say, building a service that talks to Milvus or Zilliz Cloud), treat OpenCode troubleshooting like any other dev dependency: pin versions if you need stability, keep a known-good config committed (minus secrets), and when things go sideways, reduce variables (disable plugins, use one provider, run a minimal project) until the failure reproduces cleanly.