OpenCode Not Working in Windows 11? Yeah, That Was My Fault, and Here's the Whole Embarrassing Story

OpenCode Not Working in Windows 11 happened to me on a random Saturday, and the worst part is I did it to myself — copy-pasted five files from one AI tool into another without checking if they even spoke the same language. This is the full, slightly embarrassing story of OpenCode Not Working, and the boring one-line fix that ended it.

Okay so, quick context for anyone new here: this is my personal tech diary. I write down the stuff that breaks on my own machine, because writing it down properly is more useful to me than just fixing it and forgetting.

This one's a good one. Or a dumb one, depending how you look at it.

What Happened

I use a couple of different AI coding assistants day to day — one for general dev stuff, one specifically for OpenCode, which I'd set up for parts of my blog workflow.

I decided to add five custom "subagents" to OpenCode to speed things up. Had files sitting around already, built for the other tool. Same rough shape — a Markdown file, some YAML up top, a tools: field listing what the agent's allowed to touch.

Looked close enough. Copied them straight over into OpenCode's config folder. Closed my terminal, felt productive.

Went to reopen it a few minutes later.

Nothing. Just... nothing. Not slow, not stuck loading — just refused to start, every time.

Then I Checked the Desktop App Too

Figured maybe it was just the terminal being weird, so I opened OpenCode's actual Desktop app.

Same thing. Broken. And this is a completely separate program — different install, different version number even (1.18.23 for the CLI vs 1.18.25 for Desktop). Both dead at the same time.

That's the part that actually got me curious enough to dig in properly instead of just reinstalling and hoping.

The Terminal Actually Told Me What Was Wrong

Ran opencode directly and got this before anything else even loaded:

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

Which, credit where it's due — that's a genuinely helpful error. Names the file. Names the field. Tells you it expected an object and got a list instead.

The Desktop App Was Way Less Helpful

Checked its logs next, mostly out of curiosity about whether it'd be as clear.

Nope.

Failed to load sessions Error: ConfigInvalidError
Failed to load sessions Error: ConfigInvalidError
Failed to finish bootstrap instance Error: ConfigInvalidError

Same bug, basically. Just told me nothing useful about it. No file, no field, just "something's invalid, good luck."

Why Would One File Break Two Separate Apps Though

This is the bit I actually found interesting. OpenCode's CLI and its Desktop app are genuinely separate — different installers, different folders, different version numbers.

But they both read from the same config folder on my machine, and they both spin up the same little background server when they start. The Desktop app's own log showed that server starting up just fine:

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

So the server itself was healthy. It just choked the moment it tried to read my broken agent files. Which means: break the config from anywhere — terminal, text editor, whatever — and both apps go down together. They're not actually separate, not really, not where it counts.

Okay, So What Was Actually Wrong

The files I'd copied wrote their allowed tools as a list:

tools:
  - Read
  - Write
  - Edit

OpenCode wants that same field written as more of a checklist — a map, tool name to true/false:

tools:
  read: true
  write: true
  edit: true

Both of those are perfectly fine YAML on their own. YAML's own spec just treats a list and a map as different things entirely, so it's not that my file was broken — it's that it was the wrong shape for what OpenCode specifically expects.

Checked all five files I'd added. Every single one had the same problem. Not a typo — I'd literally copied the wrong format across the board.

Also put the whole thing on video, if reading isn't your thing today:

Fixing It Was Almost Anticlimactic

Just... changed the list into a map. Five files, one line each:

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

No reinstalling anything. No clearing caches. Just fixed the text and saved.

Ran the terminal again — clean launch, first try.

Almost Convinced Myself the Fix Didn't Work

Went to double check the Desktop app and pulled up its log folder — and it STILL showed the old errors. For a solid ten seconds I thought I'd done something wrong.

Then I actually looked at the timestamp. That log was from before I'd even saved the fix. I was looking at old evidence, not a new failure.

Relaunched Desktop properly, checked the new log session, zero errors. Fixed, for real this time. Lesson noted: always check when a log was actually created before panicking about what it says.

One More Random Thing I Noticed

While poking around in my config, I saw that opencode.json is just... sitting there with real API keys in plain text. Not related to this bug at all, but worth mentioning — probably a good idea to double check your own setup isn't doing the same thing.

What I'm Taking From This One

• Copying config files between different AI tools isn't as safe as it looks, even when the format looks nearly identical.
• One bad file can take down way more than just the thing it configures.
• A CLI and its Desktop app can be way more connected under the hood than their separate installers suggest.
• Some error messages are genuinely helpful, some are basically useless — even from the same product.
• Check a log's timestamp before you trust what it's telling you.

Fun fact — I let my newsletter subscribers vote on which incident I'd write up next. Three real ones from my own machine. This one won with 69% of the vote, beating a GPU driver crash (13%) and a memory-hogging WSL issue (18%). If you want a vote next time, the newsletter is free, no spam, anyone can join.

Full technical version with every log and diff is over on my main site: istiquritconsultant.com, if you want the deep-dive version of this same story — or browse the whole Workflow Optimization archive.

Anyway — that's the full, slightly dumb, entirely self-inflicted story of OpenCode Not Working in Windows 11.

Find Me Elsewhere

• Pastebin
• Medium
• CoderLegion
• Dev.to
• Google Sites
• Substack
• GitHub
• Hashnode
• X (Twitter)
• LinkedIn