{"record":{"id":"ad76eab168778bf8","repo":"abhigyanpatwari/GitNexus","slug":"gitnexus-query-vector-message","errorCode":null,"errorMessage":"GitNexus [query:vector]: ${message}","messagePattern":"GitNexus \\[query:vector\\]: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"gitnexus/src/mcp/local/local-backend.ts","lineNumber":3487,"sourceCode":"      // Nothing was embedded on this path unless the throw happened after the\n      // vector existed (a failed lookup downstream of a good embedding, where\n      // the width IS still the live one). Clearing only in the former case\n      // keeps the recorded width a fact rather than a leftover (#2798).\n      if (embeddedDims === undefined) this.lastQueryEmbeddingDims.delete(repo.lbugPath);\n      // Embeddings disabled is the common, silent case. But a pruned or\n      // Node-unloadable optional stack (#2370/#2372) also lands here — surface it\n      // once so semantic search doesn't silently degrade to BM25 with no hint\n      // (the exact silent-degradation mode #2370 exists to fix). Emitted once per\n      // LocalBackend instance to keep stderr quiet on hot paths (like the VECTOR\n      // fallback above). All other errors stay silent, as before.\n      const message = err instanceof Error ? err.message : '';\n      if (\n        !this.warnedMissingEmbeddingStack &&\n        (isMissingLocalEmbeddingStackMessage(message) ||\n          isLocalEmbeddingRuntimeBlockerMessage(message))\n      ) {\n        this.warnedMissingEmbeddingStack = true;\n        logger.warn(`GitNexus [query:vector]: ${message}`);\n      }\n      return [];\n    }\n  }\n\n  async executeCypher(\n    repoName: string,\n    query: string,\n    params: Record<string, unknown> = {},\n  ): Promise<any> {\n    const repo = await this.resolveRepo(repoName);\n    return this.cypher(repo, { query, params });\n  }\n\n  private async cypher(\n    repo: RepoHandle,\n    // #2175: \"statement\" is the advertised param; \"query\" is the legacy alias,\n    // still accepted (and the field the internal executeCypher() passes). New wins.","sourceCodeStart":3469,"sourceCodeEnd":3505,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/0d1aed942f0e8b5d3bac27519fff441aceea722d/gitnexus/src/mcp/local/local-backend.ts#L3469-L3505","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reinstall dependencies without omitting optional deps (npm install with no --omit=optional) so the native embedding modules are present","Verify a platform-matching prebuild exists for your OS/arch, or install the toolchain (python3, make, g++) needed for the source-build fallback","Check your Node version is supported by the embedding runtime and adjust it","If the native stack cannot work in your environment, configure a remote embedding provider instead of the local one","Accept the warning if BM25-only search is acceptable: results still return, only vector ranking is lost"],"exampleFix":"# before\nnpm install --omit=optional   # embedding natives missing -> vector query warns once, degrades to BM25\n\n# after\nnpm install                   # optional native embedding deps installed -> vector query works","handlingStrategy":"validation","validationCode":"// Startup smoke test: one vector query tells you whether the local embedding\n// stack loaded. Empty result plus the one-time '[query:vector]' warning in the\n// logs means semantic search has degraded to BM25 for this process.\nconst probe = await backend.query({ repo: repoName, mode: 'vector', text: 'warmup' });\nif (probe.results.length === 0) {\n  // do not fail: BM25 answers still return; adjust expectations/UI instead.\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install without --omit=optional so the native embedding modules are present","Keep Node on a version the embedding runtime supports","After upgrades, grep logs once for '[query:vector]' — it fires once per process and is easy to miss"],"tags":["embedding","semantic-search","native-modules","optional-dependencies","fallback"],"backgroundTag":"native-module-load-failure","analyzedSha":"0d1aed942f0e8b5d3bac27519fff441aceea722d","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}