Skip to content

Commit 6511243

Browse files
neriousyneriousy
authored
feat(docs): add a desktop troubleshooting guide (#10397)
1 parent ea8d727 commit 6511243

1 file changed

Lines changed: 135 additions & 6 deletions

File tree

‎packages/web/src/content/docs/troubleshooting.mdx‎

Lines changed: 135 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,29 @@ title: Troubleshooting
33
description: Common issues and how to resolve them.
44
---
55

6-
To debug any issues with OpenCode, you can check the logs or the session data
7-
that it stores locally.
6+
To debug issues with OpenCode, start by checking the logs and local data it stores on disk.
87

98
---
109

11-
### Logs
10+
## Logs
1211

1312
Log files are written to:
1413

1514
- **macOS/Linux**: `~/.local/share/opencode/log/`
16-
- **Windows**: `%USERPROFILE%\.local\share\opencode\log\`
15+
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode\log`
1716

1817
Log files are named with timestamps (e.g., `2025-01-09T123456.log`) and the most recent 10 log files are kept.
1918

2019
You can set the log level with the `--log-level` command-line option to get more detailed debug information. For example, `opencode --log-level DEBUG`.
2120

2221
---
2322

24-
### Storage
23+
## Storage
2524

2625
opencode stores session data and other application data on disk at:
2726

2827
- **macOS/Linux**: `~/.local/share/opencode/`
29-
- **Windows**: `%USERPROFILE%\.local\share\opencode`
28+
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.local\share\opencode`
3029

3130
This directory contains:
3231

@@ -38,6 +37,132 @@ This directory contains:
3837

3938
---
4039

40+
## Desktop app
41+
42+
OpenCode Desktop runs a local OpenCode server (the `opencode-cli` sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
43+
44+
### Quick checks
45+
46+
- Fully quit and relaunch the app.
47+
- If the app shows an error screen, click **Restart** and copy the error details.
48+
- macOS only: `OpenCode` menu -> **Reload Webview** (helps if the UI is blank/frozen).
49+
50+
---
51+
52+
### Disable plugins
53+
54+
If the desktop app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.
55+
56+
#### Check the global config
57+
58+
Open your global config file and look for a `plugin` key.
59+
60+
- **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (or `~/.config/opencode/opencode.json`)
61+
- **macOS/Linux** (older installs): `~/.local/share/opencode/opencode.jsonc`
62+
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\opencode.jsonc`
63+
64+
If you have plugins configured, temporarily disable them by removing the key or setting it to an empty array:
65+
66+
```jsonc
67+
{
68+
"$schema": "https://opencode.ai/config.json",
69+
"plugin": [],
70+
}
71+
```
72+
73+
#### Check plugin directories
74+
75+
OpenCode can also load local plugins from disk. Temporarily move these out of the way (or rename the folder) and restart the desktop app:
76+
77+
- **Global plugins**
78+
- **macOS/Linux**: `~/.config/opencode/plugins/`
79+
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.config\opencode\plugins`
80+
- **Project plugins** (only if you use per-project config)
81+
- `<your-project>/.opencode/plugins/`
82+
83+
If the app starts working again, re-enable plugins one at a time to find which one is causing the issue.
84+
85+
---
86+
87+
### Clear the cache
88+
89+
If disabling plugins doesn't help (or a plugin install is stuck), clear the cache so OpenCode can rebuild it.
90+
91+
1. Quit OpenCode Desktop completely.
92+
2. Delete the cache directory:
93+
94+
- **macOS**: Finder -> `Cmd+Shift+G` -> paste `~/.cache/opencode`
95+
- **Linux**: delete `~/.cache/opencode` (or run `rm -rf ~/.cache/opencode`)
96+
- **Windows**: Press `WIN+R` and paste `%USERPROFILE%\.cache\opencode`
97+
98+
3. Restart OpenCode Desktop.
99+
100+
---
101+
102+
### Fix server connection issues
103+
104+
OpenCode Desktop can either start its own local server (default) or connect to a server URL you configured.
105+
106+
If you see a **"Connection Failed"** dialog (or the app never gets past the splash screen), check for a custom server URL.
107+
108+
#### Clear the desktop default server URL
109+
110+
From the Home screen, click the server name (with the status dot) to open the Server picker. In the **Default server** section, click **Clear**.
111+
112+
#### Remove `server.port` / `server.hostname` from your config
113+
114+
If your `opencode.json(c)` contains a `server` section, temporarily remove it and restart the desktop app.
115+
116+
#### Check environment variables
117+
118+
If you have `OPENCODE_PORT` set in your environment, the desktop app will try to use that port for the local server.
119+
120+
- Unset `OPENCODE_PORT` (or pick a free port) and restart.
121+
122+
---
123+
124+
### Linux: Wayland / X11 issues
125+
126+
On Linux, some Wayland setups can cause blank windows or compositor errors.
127+
128+
- If you're on Wayland and the app is blank/crashing, try launching with `OC_ALLOW_WAYLAND=1`.
129+
- If that makes things worse, remove it and try launching under an X11 session instead.
130+
131+
---
132+
133+
### Windows: WebView2 runtime
134+
135+
On Windows, OpenCode Desktop requires the Microsoft Edge **WebView2 Runtime**. If the app opens to a blank window or won't start, install/update WebView2 and try again.
136+
137+
---
138+
139+
### Notifications not showing
140+
141+
OpenCode Desktop only shows system notifications when:
142+
143+
- notifications are enabled for OpenCode in your OS settings, and
144+
- the app window is not focused.
145+
146+
---
147+
148+
### Reset desktop app storage (last resort)
149+
150+
If the app won't start and you can't clear settings from inside the UI, reset the desktop app's saved state.
151+
152+
1. Quit OpenCode Desktop.
153+
2. Find and delete these files (they live in the OpenCode Desktop app data directory):
154+
155+
- `opencode.settings.dat` (desktop default server URL)
156+
- `opencode.global.dat` and `opencode.workspace.*.dat` (UI state like recent servers/projects)
157+
158+
To find the directory quickly:
159+
160+
- **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support` (then search for the filenames above)
161+
- **Linux**: search under `~/.local/share` for the filenames above
162+
- **Windows**: Press `WIN+R` -> `%APPDATA%` (then search for the filenames above)
163+
164+
---
165+
41166
## Getting help
42167

43168
If you're experiencing issues with OpenCode:
@@ -113,6 +238,8 @@ To resolve this:
113238
rm -rf ~/.local/share/opencode
114239
```
115240

241+
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.local\share\opencode`
242+
116243
3. Re-authenticate with your provider using the `/connect` command in the TUI.
117244

118245
---
@@ -129,6 +256,8 @@ To resolve provider package issues:
129256
rm -rf ~/.cache/opencode
130257
```
131258

259+
On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`
260+
132261
2. Restart opencode to reinstall the latest provider packages
133262

134263
This will force opencode to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.

0 commit comments

Comments
 (0)