Learn

Troubleshooting

Check the Background Service

OpenCode uses a client-server architecture. The TUI connects to a background service that owns sessions, config, plugins, permissions, and tools. If the service is stuck or unhealthy, restart it:

opencode2 service restart

Check its status:

opencode2 service status

Common Issues

TUI shows “Starting background service…” indefinitely

The service may be booting slowly or stuck. Check:

  1. Run opencode2 service status to see the current status
  2. If status is failed, read the diagnostic message
  3. Run opencode2 service restart to force recovery

TUI shows “Waiting for background service…”

The service endpoint is unreachable. The TUI will keep retrying. If it persists:

  1. The owner process may be unresponsive (holding the lock but not responding)
  2. Run opencode2 service restart to perform explicit recovery

Gotcha: Never kill the service process manually. The OS lock guarantees one owner, and service restart verifies process identity before signaling.

Plugin not loading

Check the server log:

opencode2 api get /api/plugin

This lists active plugin IDs. If a plugin is absent:

  1. Verify the plugin file exists in .opencode/plugins/ or is installed
  2. Check for syntax errors in the plugin module
  3. One failing package does not prevent other valid packages from loading

Version mismatch after update

The background updater installs a new package, but the running service keeps the old image. A fresh TUI launch activates the update:

  1. Close existing TUIs
  2. Run opencode2 again (fresh launch)
  3. The fresh TUI detects the version difference and triggers graceful replacement

Permission denied for .env files

By default, .env files are denied for reads. Allow specific env example files:

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

Read Logs

Server logs contain plugin loading, startup, and error information. The log location depends on your platform and is printed during service startup.