0.2.2: queries against 0.2.1-built indexes fail with "zvec file metadata storage does not exist" while zg status reports healthy

[alexisdegler-sys]

Summary

After upgrading from 0.2.1 to 0.2.2, every real query against indexes built by 0.2.1 fails with:

zvec file metadata storage does not exist

zg status continues to report the indexes as ready, so the breakage is invisible to any status-level health check and only surfaces on the first actual search.

Environment

• zvec-grep 0.2.1 -> 0.2.2 (upgrade only; index files untouched)
• Linux x86_64
• 4 separate indexed roots on the same machine, all built by 0.2.1, all affected identically

Repro

1. On 0.2.1, index a root and verify queries return hits.
2. Upgrade to 0.2.2.
3. zg status -> still reported ready/healthy. No warning, no version-mismatch flag.
4. Run any real query (CLI or MCP zvec_grep_search) -> zvec file metadata storage does not exist.

Expected

Either:

• 0.2.2 reads 0.2.1-built indexes (backward compatibility), or
• zg status fails loudly with an explicit incompatible-index state and migration guidance (e.g. "re-run zg index to upgrade the index format").

Actual

Silent break: status green, queries broken. Any automation that gates adoption on zg status will adopt a release that cannot search existing indexes. My upgrade harness did exactly that: its status-level check passed, and the first real query immediately falsified it.

Workaround / recovery

Downgrade to 0.2.1 -- queries work again immediately against the untouched indexes. This confirms the 0.2.1 data is intact and this is a read/format incompatibility introduced by 0.2.2, not index corruption.

Hypothesis

The error string suggests 0.2.2 introduced (or relocated) a file-metadata storage that 0.2.1-era indexes do not contain, and the read path treats its absence as a hard runtime error instead of detecting it as a version mismatch.

Note: the natural recovery (zg index --rebuild under 0.2.2) is itself broken and destructive -- see #140.

[alexisdegler-sys]

Companion report for the recovery path: #140 -- under 0.2.2, the --rebuild I ran while recovering from this failure was itself broken and destroyed the indexes it was asked to rebuild.

[Cuiyus]

We investigated this on Linux x86_64 / ext4 using the published 0.2.1 and 0.2.2 packages, with @zvec/zvec pinned to 0.7.0 and 0.7.1 respectively.

We could not reproduce the reported failure. Testing covered:

• Four workspace roots with both deterministic embeddings and a real local model.
• CLI and MCP searches using FTS, vector, and hybrid retrieval.
• An in-place upgrade with the old daemon still running, followed by restarting with the new daemon.
• Downgrading to 0.2.1 and querying the same indexes.

All searches succeeded without rebuilding the indexes. This does not rule out a failure specific to your setup, but we have not established a general index-format incompatibility.

Could you provide the exact commands, full error context (especially path=), and the manifest’s path and rootPaths fields, with sensitive details redacted? The actual index location and whether a daemon was running would also help.

PR #144 provides useful status diagnostics, and we have identified a few adjustments needed before merging it. We’ll keep this issue open until the original failure is understood or the proposed fix is verified against a failing case.

[alexisdegler-sys]

Thanks — I went back through this machine's systemd journal and the zg daemon logs and have the complete failure record. Answers to each item, paths redacted but shapes preserved.

1. Timeline (journalctl --user -u zg-refresh.service)

A systemd user timer runs an incremental zg index <root> over 4 roots every 20 min. Under 0.2.2, every run failed:

• First failure: Sep 06 18:20:50 — Error: zvec file metadata storage does not exist
• Last failure: Sep 09 19:21:04 — 221 consecutive failures at ~20-min intervals, zero successes in between
• After downgrading the npm global to 0.2.1 (between the last failure and the next tick): every run has succeeded for 10 days since — same machine, same roots, same storage layout.

2. Exact command (verbatim unit ExecStart)

/home/<user>/.nvm/versions/node/v24.14.1/bin/zg index /home/<user>/<workspace>/<lane-A>

plus three more ExecStart= lines, one per root (three siblings inside one workspace directory, one standalone directory). So the failing surface was not only queries — the plain incremental zg index <root> read path failed identically, 221 times.

3. Full error context — why there is no path=

The CLI printed exactly Error: zvec file metadata storage does not exist and exited 1; journal verbatim:

Sep 09 18:00:51 <host> zg[3495911]: Error: zvec file metadata storage does not exist
Sep 09 18:00:51 <host> systemd[1748]: zg-refresh.service: Main process exited, code=exited, status=1/FAILURE

In the published 0.2.1 package the throw site is dist/engine/storage/zvec.js:325-332: existsSync(path) false in readOnly mode throws EngineError("zvec file metadata storage does not exist", { code: "ZVEC_GREP.ENGINE.STORAGE.ZVEC_FILE_META_MISSING", context: path=${path} }). The context: path=... payload is never printed by the CLI, so the 0.2.2-computed path was not recoverable from stdout or the journal — that may be worth fixing independently of the root cause.

4. Manifest path / rootPaths (all four roots identical shape)

{
  "path": "/home/<user>/<workspace>/<lane-A>/.zvec-grep",
  "rootPaths": [{ "absolutePath": "/home/<user>/<workspace>/<lane-A>", "recursive": true }],
  "embedding": { "provider": "local", "model": "potion-code-16m-v2", "dimension": 256, "metric": "cosine" },
  "indexVersion": 1
}

Caveat: these are from the indexes rebuilt under 0.2.1 after #140 wiped the originals; the original failing indexes were also 0.2.1-built with the same in-root layout, but I no longer have the original manifest files.

5. Index location, and a hypothesis

Storage is inside each root, not under the zvec home:

<root>/.zvec-grep/{files.zvec, index.zvec, locks/, manifest.json}

~/.zvec-grep/ holds only config.json ({"version":1,"defaults":{"embedding":"local/potion-code-16m-v2"}}), daemon/, locks/, models/. So manifest.path differs from the home directory on this setup. If the 0.2.2 oneshot path resolves file-metadata storage relative to the zvec home (the nearest.location.home vs manifest.path distinction raised in #144's review), that would produce exactly this error here while zg status stays green — and would also explain why a repro with home-resident storage sees no failure. Flagging as a hypothesis; I can't verify your internals.

6. Daemon — yes, and it was version-mixed

A long-lived zg server run --listen 127.0.0.1:7999 --mcp-toolset agent started Sep 04 09:12 and ran through the entire failure window — pre-upgrade code in memory — while the timer's CLI processes executed the upgraded 0.2.2 binary from disk. The daemon's JSON event log (16 MB, Sep 04 → today) contains zero occurrences of the error string and no error-level events in the window; the error surfaced only in 0.2.2 CLI processes. On Sep 09 09:23–09:28 the daemon restarted 6× in ~5 min (the first processes actually loading 0.2.2 from disk), stabilized 11:24; last CLI failure 19:21:04; downgrade followed.

Minimal repro candidate for your environment: under 0.2.1, index a root with in-root storage (manifest.path ≠ home), keep the 0.2.1 daemon running, npm-upgrade to 0.2.2, then run a fresh oneshot zg index <root> or query as a new CLI process.

I'm happy to re-install 0.2.2 briefly under supervision against a sacrificial root if you want the failure reproduced with any instrumentation you ship — with the context payload surfaced this time.