Skip to content

Commit ba0f8a8

Browse files
authored
Merge pull request #2717 from oscarbol09/docs/windows-troubleshooting
docs(troubleshooting): add Windows troubleshooting guide
2 parents 7b398de + 5d97172 commit ba0f8a8

2 files changed

Lines changed: 59 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1037,6 +1037,8 @@ SQLite databases stored at `~/.cache/codebase-memory-mcp/`. Persists across rest
10371037

10381038
## Troubleshooting
10391039

1040+
Windows users: see [Windows troubleshooting](docs/WINDOWS_TROUBLESHOOTING.md) for versioned known issues and workarounds.
1041+
10401042
| Problem | Fix |
10411043
|---------|-----|
10421044
| `/mcp` doesn't show the server | Check `.mcp.json` path is absolute. Restart agent. Test: `echo '{}' \| /path/to/binary` should output JSON. |

‎docs/WINDOWS_TROUBLESHOOTING.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Windows Troubleshooting
2+
3+
This page collects known Windows-specific symptoms, with the version range each affects, confirmed workarounds, and links to the canonical tracking issues.
4+
5+
## Non-ASCII paths in CBM_CACHE_DIR or CBM_ALLOWED_ROOT
6+
7+
**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.
8+
9+
**Affected versions:** Affects v0.9.x and earlier. Fixed in v0.10.0 (environment variables are read as wide strings via `GetEnvironmentVariableW`).
10+
11+
**Workaround:** On an older build, use ASCII-only paths for these two variables or upgrade with `install.ps1`.
12+
13+
**Tracking:** #1165.
14+
15+
## Upgrade completes but binary version does not change
16+
17+
**Symptom:** `codebase-memory-mcp update` reports success and downloads files, but `codebase-memory-mcp --version` still reports the previous version (with `.exe.old` remaining alongside).
18+
19+
**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.
20+
21+
**Workaround:** On an older build, run `install.ps1` once; it replaces the binary out-of-process and verifies the installed version.
22+
23+
**Tracking:** #1168 (closed; fixed in v0.10.0).
24+
25+
## Index worker hangs, crashes, or leaves an empty worker log
26+
27+
**Symptom:** `index_repository` reports worker hangs or crashes. (An *empty* worker log is a separate, fixed bug: v0.10.4 and earlier.)
28+
29+
**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. From v0.12.0, a worker that exits without returning a result is no longer counted as a success, and its log is kept. The underlying hang (#1130) and startup exit (#1145) remain open for investigation.
30+
31+
**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 still fails on v0.11.0 or newer, attach that log to #1130 or #1145.
32+
33+
**Tracking:** #1130, #1132, #1145.
34+
35+
## Antigravity 2.0 configuration not picked up
36+
37+
**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.
38+
39+
**Affected versions:** All releases through v0.12.1 when neither detection signal below is present (v0.9.x checks only for `~/.gemini/antigravity-cli`; from v0.10.0, `antigravity` on PATH also counts). The duplicate binary left behind by `install.ps1` affects v0.9.x and earlier (fixed in v0.10.0).
40+
41+
**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`.
42+
43+
**Tracking:** #1161.
44+
45+
## OpenCode installed but not detected
46+
47+
**Symptom:** `codebase-memory-mcp install` detects other clients but skips OpenCode on Windows.
48+
49+
**Affected versions:** v0.9.x and earlier detect OpenCode only through `opencode` on PATH. v0.10.0 also detects its configuration (the config file, `%USERPROFILE%\.config\opencode\`, or `OPENCODE_CONFIG_DIR`), and v0.12.0 also detects its data folder `%USERPROFILE%\.local\share\opencode\`, which the OpenCode CLI and the Desktop app both create, so detection no longer depends on PATH. In v0.12.1 and earlier, a PATH longer than 4 KB hides every CLI from detection, and npm, mise and scoop shim folders are not searched; both are fixed after v0.12.1 (#2381).
50+
51+
**Workaround:** On v0.12.0 or newer, start OpenCode once (CLI or Desktop app) so that its data folder exists, then re-run `codebase-memory-mcp install`. On v0.10.x or v0.11.0, make sure `%USERPROFILE%\.config\opencode\` exists (or point `OPENCODE_CONFIG` at an existing config file, or `OPENCODE_CONFIG_DIR` at an existing folder), then re-run `codebase-memory-mcp install`. On v0.9.x, `opencode` must be on PATH; upgrading with `install.ps1` is the simpler fix.
52+
53+
**Tracking:** #1167.
54+
55+
---
56+
57+
When a release resolves one of these issues, update or remove the corresponding entry rather than letting this page become a second issue tracker.

0 commit comments

Comments
 (0)