opencode not working windows 11

opencode not working windows 11 - quick incident log, CLI + desktop both down same time

TICKET
- what: opencode CLI (v1.18.23) and opencode Desktop (v1.18.25) both refuse to start a session
- when: immediately after adding 5 custom subagent .md files to ~/.config/opencode/agents/
- how bad: total, instant, every launch attempt, both apps

Q: what did the CLI say?
A:
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. best error message I got all week.

Q: what did desktop say?
A:
[error] Failed to load sessions Error: ConfigInvalidError  (x5)
[error] Failed to finish bootstrap instance Error: ConfigInvalidError
no file, no field. just a bare error class repeated. useless on its own.

Q: was the desktop server itself broken?
A: no. main.log showed it booting clean:
[info] spawning sidecar { url: 'http://127.0.0.1:11956' }
[info] server ready { url: 'http://127.0.0.1:11956' }
it only choked once it tried reading the bad agent files.

Q: why would 2 separate apps (different installers, different version numbers) die together?
A: they're not as separate as they look. same config root on disk, same local sidecar server spun up by both at startup. break the config anywhere, both go down.

Q: root cause?
A: tools: field written as a YAML list, copied from a different AI coding tool's subagent format:
tools:
  - Read
  - Write
  - Edit
opencode's schema wants a YAML map instead:
tools:
  read: true
  write: true
  edit: true
both valid YAML alone, different node types (list vs map) per yaml 1.2.2 spec. parses fine, fails schema check.

Q: how many files affected?
A: all 5 - blog-writer.md, blog-seo.md, blog-reviewer.md, blog-researcher.md, blog-translator.md. not a typo, a whole batch copied wrong.

Q: the fix?
A: 1 line pattern per file:
tools:
-  - Read
-  - Write
-  - Edit
+  Read: true
+  Write: true
+  Edit: true
no reinstall, no cache clear.

Q: how'd you verify it actually worked?
A: CLI - reran opencode, 0 matches for "invalid"/"error" in output.
desktop - force relaunched, checked the newest log session. almost got fooled here: first log folder I opened still showed old errors, but that session predated the fix (checked timestamp). fresh session = 0 errors in renderer.log and main.log both.

BEFORE -> AFTER
CLI startup:            fatal          -> clean launch
desktop renderer.log:   6 errors       -> 0 errors
desktop main.log:       no errors      -> no errors
bootstrap:               failed        -> succeeded

BONUS (not the bug): opencode.json stores MCP api keys in plaintext. check your own config for the same, keep it out of git.

TAKEAWAYS
- config formats don't port between AI tools automatically, even when file shape looks near-identical
- 1 malformed file can take down every entry point if validation is eager + whole-config + fail-closed
- CLI and GUI sharing 1 config root = shared failure modes regardless of separate installers
- error quality varies wildly even inside 1 product - check the CLI first if it exists
- always timestamp-check a log before trusting it during verification

full writeup: https://istiquritconsultant.com/workflow-optimization-blogs/opencode-not-working-windows-11/
more postmortems: https://istiquritconsultant.com/workflow-optimization-blogs/
newsletter, free, no spam: https://istiquritconsultant.com/no-spam-tech-newsletter/

find me elsewhere:
Medium: https://remoteseoconsultant.medium.com/
X (Twitter): https://x.com/mdistiqurrahman
Dev.to: https://dev.to/remoteseoconsultant
LinkedIn: https://www.linkedin.com/in/md-istiqur-rahman-rabby/
CoderLegion: https://coderlegion.com/user/remoteseoconsultant
Blogger: https://remoteseoconsultant.blogspot.com/
Google Sites: https://sites.google.com/view/remotegtmmanager/
GitHub: https://github.com/istiquritconsultant/blog-archive
Hashnode: https://istiqur-it-consultant.hashnode.dev/
Substack: https://istiquritconsultant.substack.com/