OpenCode Not Working in Windows 11 affected both the CLI and the Desktop application at the same time. This page documents the environment, the exact error text, the root cause, the fix, and the verification steps, for anyone who needs a quick reference on OpenCode Not Working.
Summary
Issue: OpenCode CLI and OpenCode Desktop both fail to start a session.
Cause: A tools: field written as a YAML list instead of the YAML map OpenCode's schema requires, across five custom subagent files.
Fix: Convert each tools: list to a map (Tool: true pairs). Frontmatter only, five files, one line each.
Downtime: Under one afternoon. No reinstall required.
OpenCode not working in Windows 11 reference diagram — CLI and Desktop app failure summary
## Environment
| Field | Value |
|---|---|
| OS | Windows 11 Pro Insider Preview, build 10.0.26300, 64-bit |
| OpenCode CLI | v1.18.23 (global npm install) |
| OpenCode Desktop | v1.18.25 |
| Node.js | v26.7.0 |
Both applications refuse to start a session immediately on every launch attempt. Not a slow load — an instant failure.
CLI:
Configuration is invalid at C:\Users\istiqur\.config\opencode\agents\blog-writer.md
↳ Expected object | undefined, got ["Read","Write","Edit","Grep","Glob"] tools
Desktop (renderer.log):
Failed to load sessions Error: ConfigInvalidError
Failed to finish bootstrap instance Error: ConfigInvalidError
The CLI names the file and field directly. The Desktop app's log does not — check the CLI first when both surfaces share a core.
Five subagent files under ~/.config/opencode/agents/ used this format:
yaml
tools:
- Read
- Write
- Edit
OpenCode's config schema requires:
yaml
tools:
read: true
write: true
edit: true
Both are valid YAML independently — per the YAML 1.2.2 spec, a list and a map are different node types, so the mismatch only surfaces at schema-validation time, not at parse time.
OpenCode not working fix reference — tools field YAML list to YAML map conversion
CLI and Desktop are separate installers with separate version numbers, but share one config root (~/.config/opencode/) and one local sidecar server at startup. The server itself started cleanly in both cases; the failure occurred specifically when either app asked the server to enumerate the agents directory.
## Fix
```diff
tools:
- - Read
- - Write
- - Edit
+ Read: true
+ Write: true
+ Edit: true
```
Apply to all five affected files. No reinstall, cache clear, or plugin reset needed.
## Verification
| Check | Before | After |
|---|---|---|
| CLI startup | Fatal error | Clean launch |
| Desktop renderer.log | 6 errors | 0 errors |
| Desktop main.log | No errors | No errors |
| Bootstrap | Failed | Succeeded |
Note: confirm you are reading the newest Desktop log session — compare its start timestamp against the fix's file-modification time. A pre-fix session will still show old errors and can be mistaken for a failed fix.
Before and after bar chart showing OpenCode not working errors dropping from six to zero once the tools field was fixed
opencode.json was found storing MCP service API keys in plaintext during this investigation. Unrelated to the crash, but worth an audit — keep such files out of version control.
AI subagent config formats are not portable between vendors, even with near-identical file conventions.
Whole-config, fail-closed validation means one bad file can block every entry point.
A CLI and a GUI application sharing a config root share failure modes.
Reproduce GUI failures in the CLI first, when available.
Verify log evidence against its own timestamp.
Three lessons learned from OpenCode not working, covering subagent format mismatches, blast radius, and stale log timestamps
Full technical write-up: istiquritconsultant.com — more reference posts: Workflow Optimization archive
This topic was selected by newsletter vote (69%, ahead of two other incidents at 13% and 18%). Suggestions for future reference pages welcome via the newsletter.