Skip to content
OpenCode
Esc
↑↓navigate↵open⌘Jpreview
On this page

Troubleshooting

Diagnose OpenCode startup, server, and session issues.

OpenCode runs as two processes: the TUI is a client, while a background server owns sessions, plugins, permissions, and other application state. Start by determining whether an issue is in the client, the shared server, or a specific project.

Check the background service

Show the current server status:

opencode2 service status

Verify that its API is healthy:

opencode2 api get /api/health

If the service is stuck or unhealthy, restart it:

opencode2 service restart

From inside the TUI, run /restart to restart the managed service and reconnect:

/restart

You can also stop and start it explicitly:

opencode2 service stop
opencode2 service start

Run an isolated session

Use standalone mode to run the TUI with a private server that exits with it:

opencode2 --standalone

If an issue disappears in standalone mode, it is likely related to the shared background service rather than the TUI or project itself.

Inspect the API

The api command uses the same discovery and authentication flow as the TUI. It accepts either an HTTP method and path or an OpenAPI operation ID.

See the API reference for all endpoints and operation IDs.

Pass a JSON request body with --data or -d, and add headers with --header or -H.

Read logs

Installed builds write logs to:

~/.local/share/opencode/log/opencode.log

Follow the log while reproducing the problem:

tail -f ~/.local/share/opencode/log/opencode.log

Each line includes a process run ID and a role field. Use role=cli for TUI and command startup, and role=server for session, provider, plugin, permission, and tool activity.

grep 'role=cli' ~/.local/share/opencode/log/opencode.log
grep 'role=server' ~/.local/share/opencode/log/opencode.log
grep 'run=8fc3b1d5' ~/.local/share/opencode/log/opencode.log

Increase verbosity for one reproduction:

OPENCODE_LOG_LEVEL=DEBUG opencode2

Service files

The shared server registers itself at:

~/.local/state/opencode/service.json

Its private service configuration is stored separately at:

~/.config/opencode/service.json

The database normally lives at:

~/.local/share/opencode/opencode-next.db

OPENCODE_DB can override the database location.

Explicit servers

When connecting with --server, set OPENCODE_PASSWORD if the server requires authentication:

OPENCODE_PASSWORD=secret opencode2 --server http://127.0.0.1:4096

The CLI checks the server before opening the TUI and reports whether it is unreachable, requires a password, or rejected the supplied password.

Report an issue

Include the following when reporting a reproducible problem:

  • Output from opencode2 --version
  • Output from opencode2 service status
  • The smallest sequence of steps that reproduces the issue
  • Whether the issue also occurs with opencode2 --standalone
  • Relevant log lines, including their run and role fields

Remove API keys, authorization headers, prompts, file contents, and other sensitive data before sharing logs.

Local development

When working from the OpenCode repository, run V2 commands from the repository root:

bun dev

The local development channel keeps its logs, SQLite database, and service registration separate from installed builds:

~/.local/share/opencode/log/opencode-local.log
~/.local/share/opencode/opencode-local.db
~/.local/state/opencode/service-local.json

Use the same diagnostics through the package development command:

bun dev service status
bun dev service restart
bun dev api get /api/health

Was this page helpful?