OpenCode Not Working in Windows 11: CLI + Desktop Both Fail on ConfigInvalidError — Cause and Fix

Fri, 18 Sep 2026 14:09:54 +0000

Environment: Windows 11 Pro Insider Preview (build 10.0.26300), OpenCode CLI v1.18.23, OpenCode Desktop v1.18.25, Node.js v26.7.0.

Symptom: OpenCode Not Working — both the CLI and the separately-installed Desktop app fail to start a session, immediately, on every launch attempt.

Reproduction

$ opencode --version
1.18.23
$ opencode
Configuration is invalid at C:\Users\istiqur\.config\opencode\agents\blog-writer.md
↳ Expected object | undefined, got ["Read","Write","Edit","Grep","Glob"] tools

The CLI's validator names the exact file and field. Compare against the Desktop app's renderer.log:

[error]  Failed to load sessions Error: ConfigInvalidError
[error]  Failed to load sessions Error: ConfigInvalidError
[error]  Failed to finish bootstrap instance Error: ConfigInvalidError

No file path, no field name — same failure class, far less actionable output.

Root Cause

Five custom subagent .md files under ~/.config/opencode/agents/ declared tools: as a YAML sequence:

tools:
  - Read
  - Write
  - Edit

OpenCode's config schema requires tools as a mapping (tool name → boolean):

tools:
  read: true
  write: true
  edit: true

Both shapes are valid YAML in isolation — per the YAML 1.2.2 spec, a sequence and a mapping are distinct node types, so the file parses fine and only fails when a stricter schema inspects the field. All five files carried the identical defect (list format, apparently ported from a different AI coding assistant's subagent convention), confirming a batch-import mismatch rather than an isolated typo.

Affected files:

File	Declared tools
`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

Why It Broke Both Applications

OpenCode CLI and OpenCode Desktop are separate installers (AppData\Roaming\npm\opencode vs AppData\Local\Programs\@opencode-aidesktop\OpenCode.exe) with independent version numbers and log directories. They share the same config root, ~/.config/opencode/, and both boot the same local sidecar server at startup:

[info]  spawning sidecar { url: 'http://127.0.0.1:11956' }
[info]  server ready { url: 'http://127.0.0.1:11956' }

The sidecar itself starts cleanly in both cases (main.log shows no errors) — the failure occurs specifically when the app asks the running server to enumerate the agents directory and receives the validation error back. Config errors introduced through either surface (CLI, direct file edit, another tool) will therefore surface identically on both — they are not independent configuration domains.

Watch the full breakdown on video

Fix

Frontmatter-only change, one line per file:

 tools:
-  - Read
-  - Write
-  - Edit
+  Read: true
+  Write: true
+  Edit: true

Apply to all five affected files, preserving tool names and case. No reinstall, no cache invalidation, no plugin reset required.

Verification

$ opencode
# TUI launches cleanly, 0 matches for "invalid"/"error" in captured output

For Desktop: confirm no stale opencode-named process is running, force-relaunch, and check the newest log session — not the first one alphabetically or chronologically listed. The pre-fix log session will still show the old errors and can easily be mistaken for a failed fix if you don't check its own start timestamp against the fix's file-mtime.

Check	Before	After
CLI startup	Fatal `ConfigInvalidError`	Clean launch
Desktop `renderer.log`	6 error entries	0
Desktop `main.log`	No errors (sidecar itself was fine)	No errors
Bootstrap	Failed	Succeeded

opencode.json was found to store MCP service API keys in plaintext. Unrelated to this failure, but worth an audit pass on any OpenCode install — keep such config files out of version control, source keys from environment variables where possible.

Takeaways for Anyone Running Multiple AI Coding Assistants

Subagent/plugin config schemas are not interchangeable between vendors, even with near-identical file conventions (Markdown + YAML frontmatter, tools: field present in both).
Eager, whole-config, fail-closed validation means a single malformed file can abort every entry point, not just the misconfigured agent.
A CLI and a GUI application sharing one config root will share failure modes, regardless of separate installers/versions.
Reproduce GUI failures at the CLI first when a CLI equivalent exists — error verbosity is often not consistent across surfaces of the same product.
Timestamp-check any log before trusting its contents during verification.

Full writeup (complete diffs, appendix, environment fingerprint): https://istiquritconsultant.com/workflow-optimization-blogs/opencode-not-working-windows-11/ — more postmortems: https://istiquritconsultant.com/workflow-optimization-blogs/

This topic was picked by newsletter vote (69% vs. 13% and 18% for two other incidents). Suggestions for future postmortems welcome — comment below or join the newsletter.

Coder Legion - Recent posts tagged microsoft-windows

OpenCode Not Working in Windows 11: CLI + Desktop Both Fail on ConfigInvalidError — Cause and Fix

Reproduction

Root Cause

Why It Broke Both Applications

Fix

Verification

Takeaways for Anyone Running Multiple AI Coding Assistants

Find Me Elsewhere

Coder Legion - Recent posts tagged microsoft-windows

OpenCode Not Working in Windows 11: CLI + Desktop Both Fail on ConfigInvalidError — Cause and Fix

Reproduction

Root Cause

Why It Broke Both Applications

Fix

Verification

Related Finding (Not the Root Cause)

Takeaways for Anyone Running Multiple AI Coding Assistants

Find Me Elsewhere