Repository navigation
docs: add a Windows known-issues / troubleshooting section #1170
Description
What
Propose adding a docs/WINDOWS_TROUBLESHOOTING.md (or a dedicated section in the README) that centralizes the recurring Windows-specific problems currently being reported, with known symptoms → likely cause → workaround, so new Windows users have somewhere to look before opening a duplicate issue.
Why
The issue tracker currently has a cluster of distinct-looking but related Windows reports, several opened within the same week:
- Windows: CBM_CACHE_DIR / CBM_ALLOWED_ROOT are lossily decoded — every non-ASCII char becomes U+FFFD, so the server silently uses a different path (v0.9.0) #1165 —
CBM_CACHE_DIR/CBM_ALLOWED_ROOTlossily decoded (non-ASCII → U+FFFD), causing silent path divergence or hard failures - Can't upgrade codebase-memory-mcp on windows platform. Can't uninstall. #1168 —
codebase-memory-mcp upgradereports success but the binary version doesn't actually change - Worker continuously hangs and indexing process gives up eventually #1130, Indexing worker can freeze the whole OS on binary-heavy folders, and always dies with a 0-byte log — needs resource guards and early log flush #1132, Windows-Indexing worker crashed on a file #1145 — indexing worker hangs/crashes with a 0-byte log, no way to diagnose which file caused it
- Installer targets legacy Gemini-CLI settings.json instead of Antigravity 2.0 config directory (resulting in duplicate 273MB binaries) #1161 — installer targets the legacy Gemini-CLI
settings.jsoninstead of the Antigravity 2.0 modular config, and can leave duplicate 273MB binaries on disk - fails to install for opencode on windows (other os's unknown) #1167 —
installfails to detect OpenCode on Windows even when both the CLI and app are installed
Each is already tracked individually and should stay that way for the actual fixes, but a lot of the diagnostic value (e.g. "if config list fails with cannot open config database, check for non-ASCII in your Windows username — see #1165") is currently locked inside individual issue threads. A short troubleshooting doc would reduce duplicate reports and give maintainers something to link to when triaging new Windows issues.
Proposal
- New file:
docs/WINDOWS_TROUBLESHOOTING.md, linked from the README's existing Troubleshooting table. - Structure: one entry per known class of problem (symptom, root cause if known, workaround if one exists, link to the tracking issue), kept in sync as those issues get fixed/closed.
- Scope is documentation only — no code changes, so it doesn't touch any of the higher-risk areas in
MAINTAINERS.md.
Happy to draft the content and open a PR once the location/format is confirmed by a maintainer, per the "open an issue first" contribution guideline.
Activity
DeusData commentedon Jul 22, 2026
Yes, please use a dedicated
docs/WINDOWS_TROUBLESHOOTING.mdlinked from the README Troubleshooting section. Keep each entry limited to a confirmed symptom, affected version range when known, current workaround, and canonical tracking issue. Avoid asserting a root cause until it is verified, and remove or update entries when a release resolves them. That keeps the document useful without turning it into a second issue tracker.DeusData commentedon Oct 19, 2026
Thank you for offering to draft the Windows troubleshooting guide. The location and scope agreed above still provide the starting point: confirmed symptoms, affected versions, workarounds, and canonical issues. If you have a draft in progress, please link it here so the discussion stays connected.
oscarbol09 commentedon Oct 19, 2026
I've opened PR #2717 with the draft of \docs/WINDOWS_TROUBLESHOOTING.md\ linked from the README Troubleshooting section.
The guide structures each entry around confirmed symptoms, affected version ranges, workarounds, and canonical tracking issues, incorporating the status up through v0.11.0 (such as wide-character environment decoding and out-of-process update handoff).
(Note: Posted on behalf of @oscarbol09 with Antigravity assistance per contribution guidelines)
docs(troubleshooting): refresh Windows entries for v0.12.x
docs(troubleshooting): add Windows troubleshooting guide
DeusData commentedon Oct 29, 2026
The Windows troubleshooting page proposed here is on main: docs/WINDOWS_TROUBLESHOOTING.md, added by #2717 (merge ba0f8a8) from @oscarbol09, with the structure first drafted by @tamerbak in #2262. Each entry lists the symptom, affected versions, workaround and tracking issue. Closing this as completed; new Windows problems are very welcome as their own issues. Thank you for the proposal!