Troubleshooting

OpenCode uses a client-server architecture. A background server owns sessions, plugins, permissions, and other application state. Start by determining whether an issue is in a 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

You can also stop and start it explicitly:

opencode2 service stop
opencode2 service start

Allow a browser origin

If a browser client on another origin cannot connect because of CORS, add the client’s origin to the service configuration:

opencode2 service set cors http://192.168.1.10:3001
opencode2 service get cors

Use an exact HTTP or HTTPS origin, including the port when needed, without a path or trailing slash. To allow multiple origins, pass a comma-separated list as one argument; whitespace around each origin is trimmed:

opencode2 service set cors "http://192.168.1.10:3001, https://app.example.com"

service get cors prints a JSON array. Remove the configured list with:

opencode2 service unset cors

Setting or unsetting service configuration stops the background service. Its next start picks up the new configuration; use opencode2 service start to start it explicitly.

For a foreground server, repeat --cors for each additional allowed origin:

opencode2 serve --cors http://192.168.1.10:3001 --cors https://app.example.com

With serve --service, supplied --cors flags override the persisted list for that process. Without those flags, service mode uses the persisted list. CORS does not change the listening address or bypass server authentication.

Inspect the API

The api command uses the local service discovery and authentication flow. 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=server for session, provider, plugin, permission, and tool activity.

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

Capture CPU and memory profiles

On macOS and Linux, you can signal a running OpenCode process to capture diagnostic data. Get the background server PID from the health endpoint:

opencode2 api get /api/health

Use the pid from the response with one of these signals:

• SIGPROF captures a ten-second CPU profile:

  kill -SIGPROF <pid>

  The result is written to the log directory as cpu-<pid>-<timestamp>.cpuprofile.

• SIGUSR1 captures a memory (heap) snapshot:

  kill -SIGUSR1 <pid>

  The result is written to the log directory as heap-<pid>-<timestamp>.heapsnapshot.

Wait for CPU profile written or heap snapshot written in opencode.log before opening the file. The corresponding log entry includes its complete path. You can inspect both file types in Chrome DevTools.

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.db

OPENCODE_DB can override the database location.

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 affects the shared service, a specific client, or one project
• Relevant log lines, including their run and role fields

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

File reproducible problems in GitHub Issues.