TL;DR: OpenCode not working in Windows 11, on both the CLI and Desktop app simultaneously, traced back to one field: tools: written as a YAML list instead of the map OpenCode's schema expects. Fixed in five files, one line each, no reinstall. Full breakdown below, primary keyword: OpenCode Not Working.
I run a small AI-assisted content workflow on a laptop — nothing fancy, an AMD Ryzen 5 box, 16GB RAM, Windows 11 Pro. I added five custom subagents to OpenCode to automate parts of my blog pipeline: a writer, an SEO checker, a reviewer, a researcher, a translator.
I copied the subagent files from a different AI coding assistant I already run daily. Same surface shape — Markdown + YAML frontmatter, a tools: field, a description: field. Dropped them into ~/.config/opencode/agents/ and closed my terminal.
That's the whole mistake, and it took down two apps at once.
The Symptom
Reopened opencode in my terminal a few minutes later. Instant failure, every launch — not a hang, a flat refusal.
Opened OpenCode Desktop next. Same thing. Different installer (v1.18.25 vs the CLI's v1.18.23), same failure, same moment.
Reproduce in the CLI First
This is the actual engineering lesson buried in this post: when a GUI tool built on a shared core fails mysteriously, reproduce it in the CLI first if one exists. The CLI's error output is almost always more actionable.
Here, it was:
Configuration is invalid at C:\Users\istiqur\.config\opencode\agents\blog-writer.md
↳ Expected object | undefined, got ["Read","Write","Edit","Grep","Glob"] tools
Exact file. Exact field. Expected type vs. actual type, right there in the error string.
What the Desktop App Logged Instead
[2026-08-30 14:11:29.555] [error] Failed to load sessions Error: ConfigInvalidError
[2026-08-30 14:11:29.580] [error] Failed to load sessions Error: ConfigInvalidError
[2026-08-30 14:11:36.928] [error] Failed to finish bootstrap instance Error: ConfigInvalidError
Same underlying failure. Zero file path, zero field name — just a bare error class, repeated, then a hard bootstrap failure.
Root Cause: Why the Same File Broke Both Apps
OpenCode's CLI and Desktop app aren't the same binary. Different installers, different version numbers, different log directories. But they share one thing: the config root at ~/.config/opencode/, and the same local sidecar server on startup.
Desktop's main.log proved the server itself booted clean:
[info] spawning sidecar { url: 'http://127.0.0.1:11956' }
[info] server ready { url: 'http://127.0.0.1:11956' }
The server came up green. It only failed once the renderer asked it to enumerate the agents directory and hit the malformed file. Any config problem introduced on disk surfaces identically in both apps — they're not independent configuration surfaces, whatever their version numbers suggest.
The Actual Bug
The subagent files I'd added declared tools: as a YAML sequence:
tools:
- Read
- Write
- Edit
OpenCode's config schema expects a mapping — tool name to boolean:
tools:
read: true
write: true
edit: true
Both parse as valid YAML. The YAML 1.2.2 spec defines sequences and mappings as distinct node types, so a file can be syntactically fine and still fail a target schema that expects the other shape. All five files I'd added used the list format — a batch import from the wrong source, not a one-off typo:
| File | Tools declared |
|---|---|
blog-writer.md |
Read, Write, Edit, Grep, Glob |
blog-seo.md |
Read, Grep, Glob |
blog-reviewer.md |
Read, Grep, Glob |
blog-researcher.md |
WebSearch, WebFetch, Read, Grep, Glob |
blog-translator.md |
Read, Write, Edit, Glob, Grep |
Watch the full breakdown on video:
The Fix
tools:
- - Read
- - Write
- - Edit
+ Read: true
+ Write: true
+ Edit: true
Same pattern, five files, frontmatter only. No reinstall, no cache clear.
opencode
# → TUI launches cleanly
# → 0 matches for "invalid" / "error"
Verifying the Fix on Desktop (Don't Skip This Part)
The first Desktop log folder I checked still showed the old errors. For about ten seconds I thought the fix hadn't worked.
Then I checked the log session's own start timestamp against my fix's file-modification time — that log session predated the fix. Stale evidence, not a failed fix.
Force-relaunched Desktop, found the fresh session, grepped renderer.log and main.log for invalid|error — zero matches in both.
| Check | Before fix | After fix |
|------------------------|--------------------------|----------------------|
| CLI startup | Fatal config error | Clean launch |
| Desktop renderer.log | 6 ConfigInvalidError | 0 errors |
| Desktop main.log | No errors (server fine) | No errors |
| Bootstrap | Failed | Succeeded |
One Unrelated Thing Worth Flagging
While in there, I noticed opencode.json stores live MCP service API keys in plain text. Not related to this bug, but worth checking your own config for — keep files like that out of version control, prefer env vars for live keys.
Takeaways
- Subagent config formats don't port between AI coding tools by default — a YAML list vs. map difference is enough to break everything.
- Eager, fail-closed whole-config validation means one bad file takes down every entry point, not just the broken agent.
- A CLI and its GUI sibling can share failure modes invisibly, even shipped as separate installers.
- Error message quality varies a lot by surface, even inside one product — reproduce in the CLI first.
- Always check a log's own timestamp against your fix's timestamp before trusting it.
Full write-up with the complete diff set and appendix: istiquritconsultant.com — more like it in the Workflow Optimization archive.
This post won a reader vote — I asked my newsletter (5,078 subscribers) to pick between three real incidents from my machine: this one (69%), a GPU driver crash on charger-plug (13%), and a vmmem memory leak after using WSL (18%). If you want a vote on what's next, the newsletter is free and spam-free. Suggestions welcome in the comments too.
That's the full story behind OpenCode Not Working in Windows 11 — one field, two apps, one afternoon.
Top comments (0)