Skip to content

docs(troubleshooting): add Windows troubleshooting guide #2717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oscarbol09 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(troubleshooting): add Windows troubleshooting guide #2717

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a933d53
docs(troubleshooting): add Windows troubleshooting guide
oscarbol09 Oct 19, 2026
d1ab242
Merge branch 'main' into docs/windows-troubleshooting
oscarbol09 Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -986,6 +986,8 @@ SQLite databases stored at `~/.cache/codebase-memory-mcp/`. Persists across rest

## Troubleshooting

Windows users: see [Windows troubleshooting](docs/WINDOWS_TROUBLESHOOTING.md) for versioned known issues and workarounds.

| Problem | Fix |
|---------|-----|
| `/mcp` doesn't show the server | Check `.mcp.json` path is absolute. Restart agent. Test: `echo '{}' \| /path/to/binary` should output JSON. |
Expand Down
57 changes: 57 additions & 0 deletions docs/WINDOWS_TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Windows Troubleshooting

This page collects known Windows-specific symptoms, with the version range each affects, confirmed workarounds, and links to the canonical tracking issues.

## Non-ASCII paths in CBM_CACHE_DIR or CBM_ALLOWED_ROOT

**Symptom:** Configuration appears not to persist, the config database cannot be opened (`error: cannot open config database`), or repositories inside `CBM_ALLOWED_ROOT` are rejected during indexing.

**Affected versions:** Affects v0.9.x and earlier. Fixed in v0.10.0 (environment variables are read as wide strings via `GetEnvironmentVariableW`).

**Workaround:** On an older build, use ASCII-only paths for these two variables (e.g. via an NTFS junction) or upgrade with `install.ps1`.

**Tracking:** #1165.

## Upgrade completes but binary version does not change

**Symptom:** `codebase-memory-mcp upgrade` reports success and downloads files, but `codebase-memory-mcp --version` still reports the previous version (with `.exe.old` remaining alongside).

**Affected versions:** Affects v0.9.x and earlier (in-process self-update on Windows). From v0.10.0, `update` prints the `install.ps1` command instead of replacing itself.

**Workaround:** On an older build, run `install.ps1` once; it replaces the binary out-of-process and verifies the installed version.

**Tracking:** #1168.

## Index worker hangs, crashes, or leaves an empty worker log

**Symptom:** `index_repository` reports worker hangs or crashes. (An *empty* worker log is a separate, fixed bug: v0.10.4 and earlier.)

**Affected versions:** Empty worker logs affect v0.10.4 and earlier (fixed in v0.10.5). Misleading "crashed on a file" reports for returned errors fixed in v0.10.0. From v0.11.0, the Windows worker is memory-capped. The underlying hang (#1130) and startup exit (#1145) remain open for investigation.

**Workaround:** For repositories containing large binary, media, or model directories, exclude those paths with `.cbmignore` before indexing (see [`.cbmignore` documentation](cbmignore.md)). From v0.10.5, the worker log names the in-flight file; if indexing fails on v0.11.0, attach that log to #1130 or #1145.

**Tracking:** #1130, #1132, #1145.

## Antigravity 2.0 configuration not picked up

**Symptom:** Installation completes but Antigravity 2.0 does not see the MCP server or hooks, or the environment is detected as Gemini-CLI; duplicate large binaries may also be left on disk.

**Affected versions:** Affects detection when neither `~/.gemini/antigravity-cli` exists nor `antigravity` is found on PATH. Duplicate binary accumulation during `install.ps1` fixed since v0.10.0.

**Workaround:** Antigravity is configured only when `~/.gemini/antigravity-cli` exists or `antigravity` is on PATH; the target is `~/.gemini/config/mcp_config.json`, and no hooks are installed for it. If neither signal is present, the machine is treated as Gemini-CLI. From v0.10.0, `install.ps1` keeps a single binary; running `codebase-memory-mcp install` manually without `--dir` can still create a second copy in `~/.local/bin`.

**Tracking:** #1161.

## OpenCode installed but not detected

**Symptom:** `codebase-memory-mcp install` detects other clients but skips OpenCode on Windows.

**Affected versions:** Affects v0.9.x and earlier with PATH-only detection. From v0.10.0, OpenCode is also detected via its configuration directory. PATH-only detection can still fail on Windows (long PATH strings, non-ASCII user profiles, or npm shim directory paths).

**Workaround:** Ensure `%USERPROFILE%\.config\opencode\` exists (or set `OPENCODE_CONFIG` / `OPENCODE_CONFIG_DIR`), then re-run `codebase-memory-mcp install`.

**Tracking:** #1167.

---

When a release resolves one of these issues, update or remove the corresponding entry rather than letting this page become a second issue tracker.
Loading