OpenCode: Connection Failed

What it means

OpenCode Desktop could not reach its OpenCode server. Desktop runs a local server (the opencode-cli sidecar) by default, or connects to a server URL you configured. The docs cover this dialog and an app stuck on the splash screen.

Causes

• A custom default server URL is set in the desktop app (official docs).
• A server section (server.port or server.hostname) in opencode.json(c) (official docs).
• OPENCODE_PORT is set in the environment, so the app tries to use that port (official docs).
• A misbehaving plugin or corrupted cache. The docs name these as the most common causes of desktop issues.

How to fix it

1. 1
   Fix 1.

   On the Home screen, click the server name (with the status dot) to open the Server picker. In the Default server section, click Clear.

2. 2
   Fix 2.

   Temporarily remove the server section from opencode.json(c) and restart the app.

3. 3
   Fix 3.

   Unset OPENCODE_PORT (or pick a free port) and restart.

   Terminal

   Copy

   unset OPENCODE_PORT

4. 4
   Fix 4.

   Disable plugins in the global config (~/.config/opencode/opencode.jsonc), then clear the cache and restart.

   JSON

   Copy

   {
     "$schema": "https://opencode.ai/config.json",
     "plugin": [],
   }
   
   rm -rf ~/.cache/opencode

5. 5
   Fix 5.

   Last resort: quit the app and delete opencode.settings.dat (desktop default server URL), plus opencode.global.dat and opencode.workspace.*.dat, from the OpenCode Desktop app data directory.