abhigyanpatwari/GitNexus · warning

GitNexus [query:vector]: ${message}

Error message

GitNexus [query:vector]: ${message}

What it means

A GitNexus semantic (vector) query on a local index catches every error from the local embedding stack. When the failure message matches the missing-local-embedding-stack or runtime-blocker patterns (optional native modules Node could not load, issues #2370/#2372), LocalBackend logs this warning exactly once per instance and returns an empty result list, so semantic search degrades to BM25 instead of failing hard. The once-per-instance emission keeps stderr quiet on hot paths while still making the degradation visible.

Source

Thrown at gitnexus/src/mcp/local/local-backend.ts:3487

      // Nothing was embedded on this path unless the throw happened after the
      // vector existed (a failed lookup downstream of a good embedding, where
      // the width IS still the live one). Clearing only in the former case
      // keeps the recorded width a fact rather than a leftover (#2798).
      if (embeddedDims === undefined) this.lastQueryEmbeddingDims.delete(repo.lbugPath);
      // Embeddings disabled is the common, silent case. But a pruned or
      // Node-unloadable optional stack (#2370/#2372) also lands here — surface it
      // once so semantic search doesn't silently degrade to BM25 with no hint
      // (the exact silent-degradation mode #2370 exists to fix). Emitted once per
      // LocalBackend instance to keep stderr quiet on hot paths (like the VECTOR
      // fallback above). All other errors stay silent, as before.
      const message = err instanceof Error ? err.message : '';
      if (
        !this.warnedMissingEmbeddingStack &&
        (isMissingLocalEmbeddingStackMessage(message) ||
          isLocalEmbeddingRuntimeBlockerMessage(message))
      ) {
        this.warnedMissingEmbeddingStack = true;
        logger.warn(`GitNexus [query:vector]: ${message}`);
      }
      return [];
    }
  }

  async executeCypher(
    repoName: string,
    query: string,
    params: Record<string, unknown> = {},
  ): Promise<any> {
    const repo = await this.resolveRepo(repoName);
    return this.cypher(repo, { query, params });
  }

  private async cypher(
    repo: RepoHandle,
    // #2175: "statement" is the advertised param; "query" is the legacy alias,
    // still accepted (and the field the internal executeCypher() passes). New wins.

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Reinstall dependencies without omitting optional deps (npm install with no --omit=optional) so the native embedding modules are present
2. Verify a platform-matching prebuild exists for your OS/arch, or install the toolchain (python3, make, g++) needed for the source-build fallback
3. Check your Node version is supported by the embedding runtime and adjust it
4. If the native stack cannot work in your environment, configure a remote embedding provider instead of the local one
5. Accept the warning if BM25-only search is acceptable: results still return, only vector ranking is lost

Example fix

# before
npm install --omit=optional   # embedding natives missing -> vector query warns once, degrades to BM25

# after
npm install                   # optional native embedding deps installed -> vector query works

// Startup smoke test: one vector query tells you whether the local embedding
// stack loaded. Empty result plus the one-time '[query:vector]' warning in the
// logs means semantic search has degraded to BM25 for this process.
const probe = await backend.query({ repo: repoName, mode: 'vector', text: 'warmup' });
if (probe.results.length === 0) {
  // do not fail: BM25 answers still return; adjust expectations/UI instead.
}

When it happens

Trigger: Calling the query API with vector/semantic search enabled (routed through LocalBackend's vector path) on a machine where the local embedding runtime cannot start: the optional native embedding dependency failed to load, or a runtime blocker was detected from the error message. All other vector errors stay silent, as before.

Common situations: npm install ran with --omit=optional so the native embedding modules were never installed; a platform/arch with no prebuilt embedding binary and no toolchain to source-build; a Node version the native addon cannot load under; CI images that trim optional dependencies. Search still returns results, but semantic ranking is silently lost.

Related errors

• Local semantic embeddings are unavailable: the optional embe
• Embedding model not initialized. Run embedding pipeline firs
• Local semantic embeddings are unavailable: the optional embe
• Worker ${i} hit a deterministic startup crash-loop; dropping
• Worker ${i} crashed during startup; respawning slot (self-he

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-08-20). Data as JSON: /api/errors/ad76eab168778bf8. Report an issue: GitHub.