Dax
120 lines
3.1 KiB
Plaintext
120 lines
3.1 KiB
Plaintext
---
|
|
title: "Troubleshooting"
|
|
---
|
|
|
|
<Callout type="tip">
|
|
You can ask OpenCode to debug itself. Describe the problem and ask it to use this troubleshooting page; it can read
|
|
the steps below, inspect its service and logs, and help identify the issue.
|
|
</Callout>
|
|
|
|
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:
|
|
|
|
```bash
|
|
opencode2 service status
|
|
```
|
|
|
|
Verify that its API is healthy:
|
|
|
|
```bash
|
|
opencode2 api get /api/health
|
|
```
|
|
|
|
If the service is stuck or unhealthy, restart it:
|
|
|
|
```bash
|
|
opencode2 service restart
|
|
```
|
|
|
|
You can also stop and start it explicitly:
|
|
|
|
```bash
|
|
opencode2 service stop
|
|
opencode2 service start
|
|
```
|
|
|
|
<Callout type="note">
|
|
OpenCode normally discovers or starts the shared background service automatically. The service commands are only
|
|
needed when diagnosing its lifecycle.
|
|
</Callout>
|
|
|
|
## 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](/api) for all endpoints and operation IDs.
|
|
|
|
Pass a JSON request body with `--data` or `-d`, and add headers with `--header` or `-H`.
|
|
|
|
<Callout type="warning">
|
|
Running `opencode2 api` may start the background service when no compatible healthy service is available.
|
|
</Callout>
|
|
|
|
## Read logs
|
|
|
|
Installed builds write logs to:
|
|
|
|
```text
|
|
~/.local/share/opencode/log/opencode.log
|
|
```
|
|
|
|
Follow the log while reproducing the problem:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
grep 'role=server' ~/.local/share/opencode/log/opencode.log
|
|
grep 'run=8fc3b1d5' ~/.local/share/opencode/log/opencode.log
|
|
```
|
|
|
|
## Service files
|
|
|
|
The shared server registers itself at:
|
|
|
|
```text
|
|
~/.local/state/opencode/service.json
|
|
```
|
|
|
|
Its private service configuration is stored separately at:
|
|
|
|
```text
|
|
~/.config/opencode/service.json
|
|
```
|
|
|
|
The database normally lives at:
|
|
|
|
```text
|
|
~/.local/share/opencode/opencode.db
|
|
```
|
|
|
|
`OPENCODE_DB` can override the database location.
|
|
|
|
<Callout type="warning">
|
|
Do not delete or edit service files or the database while troubleshooting. Use the service commands to manage the
|
|
daemon, and make a backup before inspecting persistent data with external tools.
|
|
</Callout>
|
|
|
|
## 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](https://github.com/anomalyco/opencode/issues).
|