# OpenCode Not Working in Windows 11? I Broke Both My CLI and Desktop App With One Copy-Paste

OpenCode not working in Windows 11 is the kind of bug that makes you feel a specific flavor of stupid — not because it's hard, but because you did it to yourself, in about thirty seconds, without thinking twice.

Here's the full story: what broke, why it took down two separate applications at once, and the one-line fix that ended it.

## Setting the Scene

I run a small AI-assisted content workflow. Nothing exotic — a laptop, a few coding assistants I lean on for repetitive work, and OpenCode handling part of my blog pipeline.

I decided to add five custom subagents to speed things up: a writer, an SEO checker, a reviewer, a researcher, a translator. I had files sitting around already, built for a different AI coding assistant I also run daily. Same surface shape — Markdown, YAML frontmatter, a `tools:` field.

I copied them straight into OpenCode's config folder. Closed the terminal. Moved on with my day.

*That was the entire mistake.*

## Two Apps, Same Moment, Same Failure

A few minutes later I reopened my terminal to keep working.

Nothing. Not a slow load, not a hang — a flat, immediate refusal to start, every single time.

I opened OpenCode's Desktop app next, half-expecting it to just work. It didn't. Same dead-on-arrival behavior, and this is a genuinely separate application: different installer, different version number (1.18.23 for the CLI, 1.18.25 for Desktop).

Two apps, same instant, same failure, for a reason neither one explained clearly up front.

### What the CLI Told Me (Everything)

Running `opencode` directly in the terminal produced this before any interface even rendered:

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

That's a genuinely well-designed error. It names the file. It names the field. It tells you what type it expected versus what it actually got. If I'd read it carefully the first time, this would've been a five-minute fix instead of a proper investigation.

### What the Desktop App Told Me (Almost Nothing)

Curious whether the GUI would be equally specific, I checked its logs too:

```plaintext
[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
```

No file. No field. Just a bare error class, repeated, then a hard stop. Same underlying failure as the CLI — wildly different diagnostic value depending on which surface happened to be in front of me.

## Why One File Took Down Two "Separate" Apps

Here's the part worth actually remembering past this one incident.

OpenCode's CLI and Desktop app are not the same binary. Different installers, different data folders, different version numbers. But they share one thing that matters more than any of that: the same config directory on disk, `~/.config/opencode/`, and the same local sidecar server spun up at startup.

Desktop's own startup log proved the server itself was healthy:

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

Clean startup. It only failed once it tried to actually enumerate my agents folder and hit the malformed file. If a CLI tool and its GUI counterpart share a config directory, breaking one from the command line breaks the other — no separate installer changes that.

### Root Cause: A List Where a Map Was Expected

The five files I'd added declared their allowed tools as a YAML **list** — the format a different AI coding assistant uses for its own subagents:

```yaml
yaml
tools:
  - Read
  - Write
  - Edit
```

[**OpenCode's config schema**](https://opencode.ai/docs/config/) **requires the same field as a YAML map instead, tool name to boolean:**

```yaml
yaml
tools:
  read: true
  write: true
  edit: true
```

Both are completely valid YAML on their own terms. [The YAML 1.2.2 specification](https://yaml.org/spec/1.2.2/) treats a sequence and a mapping as fundamentally different node types, so a file can parse cleanly and still fail a schema check the moment a stricter tool inspects its shape.

All five files I'd added carried the identical defect:

*   [`blog-writer.md`](http://blog-writer.md)
    
*   [`blog-seo.md`](http://blog-seo.md)
    
*   [`blog-reviewer.md`](http://blog-reviewer.md)
    
*   [`blog-researcher.md`](http://blog-researcher.md)
    
*   [`blog-translator.md`](http://blog-translator.md)
    

Not one typo. A whole batch, carried over from the wrong source, without translating the schema.

![Diagram comparing the YAML list format that caused OpenCode not working against the YAML map format OpenCode actually expects](https://cdn.hashnode.com/uploads/covers/6a8d1fe2dad5fe90ac1c1e8d/deb2407a-f0ee-42d8-bc1f-e8ecec52c2a2.png align="center")

***Full breakdown on video:***

%[https://www.youtube.com/watch?v=jZcRgkG01Gg] 

## The Fix Took One Line Per File

```yaml
diff
 tools:
-  - Read
-  - Write
-  - Edit
+  Read: true
+  Write: true
+  Edit: true
```

Repeat that pattern across all five files, save, relaunch. No reinstall, no cache clear, no forum thread required. The CLI came up clean on the first try — zero matches for "invalid" or "error" in the captured output.

### Verifying the Desktop App (Where I Almost Fooled Myself)

> I checked OpenCode Desktop's log folder right after the fix and still saw the old errors. Ten seconds of quiet panic followed.

Then I noticed the timestamp. That log session had started *before* my fix was even saved — stale evidence, not a failed fix. Comparing a log session's own start time against your fix's file-modification time before trusting it is a small habit that saves a lot of confusion. Force-relaunching Desktop and checking the fresh session confirmed zero errors across both `renderer.log` and `main.log`.

![Before and after bar chart showing OpenCode not working errors dropping from six to zero once the tools field was fixed](https://cdn.hashnode.com/uploads/covers/6a8d1fe2dad5fe90ac1c1e8d/f3122c2d-6182-46a3-9455-665f6f9bb6ff.png align="center")

## One More Thing, Unrelated to the Bug

<mark class="bg-yellow-200 dark:bg-yellow-500/30">While digging through my own config, I noticed </mark> `opencode.json` <mark class="bg-yellow-200 dark:bg-yellow-500/30">stores live API keys for a couple of MCP services in plain text. Not a crash risk — a quiet one. Worth checking your own setup for the same thing, regardless of which AI tools you run.</mark>

### What I'm Keeping From This

1.  Subagent formats don't travel between AI coding tools automatically — a list and a map can look almost identical and still be incompatible underneath.
    
2.  Eager, whole-config validation has a real blast radius — one bad file took down every entry point.
    
3.  A CLI and its GUI sibling can share failure modes invisibly, even with separate installers and version numbers.
    
4.  Error message quality is inconsistent even within one product — reproduce in the CLI first when a GUI app goes quiet.
    
5.  Never trust a log without checking its timestamp against your fix.
    

![Three lessons learned from OpenCode not working, covering subagent format mismatches, blast radius, and stale log timestamps](https://cdn.hashnode.com/uploads/covers/6a8d1fe2dad5fe90ac1c1e8d/54419f10-f0a9-41df-9a85-7c6ec83871a2.png align="center")

## Why I Wrote This One Specifically

I asked my newsletter subscribers to vote on what I'd write about next — three real incidents from my own machine, one vote each. This one, the OpenCode Not Working postmortem, won with 69% of the vote, ahead of a GPU driver crash on charger-plug (13%) and a `vmmem` memory leak after using WSL (18%). If you want a say in what gets picked next, [the newsletter](https://istiquritconsultant.com/no-spam-tech-newsletter/) is free, has no spam, and anyone can join or leave anytime.

The complete technical write-up — every log, table, and diff — lives at [istiquritconsultant.com](http://istiquritconsultant.com), if you want the full reference version — or browse the [full Workflow Optimization archive](https://istiquritconsultant.com/workflow-optimization-blogs/).

If you're dealing with OpenCode Not Working in Windows 11 right now: check the CLI first, check your `tools:` field's shape second, and don't trust a stale log third. That's genuinely the whole fix.

### Find Me Elsewhere

*   [Dev.to](http://Dev.to)
    
*   [X (Twitter)](https://x.com/mdistiqurrahman)
    
*   [Medium](https://remoteseoconsultant.medium.com/)
    
*   [Substack](https://istiquritconsultant.substack.com/)
    
*   [Blogger](https://remoteseoconsultant.blogspot.com/)
    
*   [Google Sites](https://sites.google.com/view/remotegtmmanager/)
    
*   [Pastebin](https://pastebin.com/u/remotegtmmanager)
    
*   [GitHub](https://github.com/istiquritconsultant/blog-archive)
    
*   [LinkedIn](https://www.linkedin.com/in/md-istiqur-rahman-rabby/)
    
*   [CoderLegion](https://coderlegion.com/user/remoteseoconsultant)