{"record":{"id":"64a822b1e429e1e5","repo":"abhigyanpatwari/GitNexus","slug":"local-semantic-embeddings-are-unavailable-the-opt-64a822","errorCode":null,"errorMessage":"Local semantic embeddings are unavailable: the optional embedding stack is not installed.\nnpm skipped the optional packages @huggingface/transformers / onnxruntime-node\nduring install — usually because onnxruntime-node's postinstall could not\ndownload its CUDA support binaries from api.nuget.org (common behind HTTP\nproxies and regional firewalls, #2370). Everything except local embeddings\nstill works.\n\nTo enable local embeddings:\n  - Run `gitnexus embeddings install` — fetches the stack on demand through\n    your npm registry config (mirrors and proxies apply; no NuGet download).\n    `gitnexus analyze --embeddings` does this automatically.\n    Add --cuda on CUDA GPU hosts (behind a proxy, also set\n    GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download).\n  - Or reinstall with the CUDA download skipped (CPU embeddings need no CUDA):\n      ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus\n      (Windows: set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus)\n  - Or point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an\n    OpenAI-compatible /v1/embeddings endpoint to embed over HTTP.","messagePattern":"Local semantic embeddings are unavailable: the optional embedding stack is not installed\\.\nnpm skipped the optional packages @huggingface/transformers / onnxruntime-node\nduring install — usually because onnxruntime-node's postinstall could not\ndownload its CUDA support binaries from api\\.nuget\\.org \\(common behind HTTP\nproxies and regional firewalls, #2370\\)\\. Everything except local embeddings\nstill works\\.\n\nTo enable local embeddings:\n  - Run `gitnexus embeddings install` — fetches the stack on demand through\n    your npm registry config \\(mirrors and proxies apply; no NuGet download\\)\\.\n    `gitnexus analyze --embeddings` does this automatically\\.\n    Add --cuda on CUDA GPU hosts \\(behind a proxy, also set\n    GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download\\)\\.\n  - Or reinstall with the CUDA download skipped \\(CPU embeddings need no CUDA\\):\n      ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus\n      \\(Windows: set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus\\)\n  - Or point GITNEXUS_EMBEDDING_URL \\(with GITNEXUS_EMBEDDING_MODEL\\) at an\n    OpenAI-compatible /v1/embeddings endpoint to embed over HTTP\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/mcp/core/embedder.ts","lineNumber":94,"sourceCode":"      // install time (#2370), its bare specifiers fall back to the on-demand\n      // runtime prefix.\n      ensureEmbeddingStackResolvable();\n      // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`\n      // import is unresolvable; register the fallback resolver first (#307).\n      ensureOnnxRuntimeCommonResolvable();\n      // Registered AFTER the common fallback so this hook resolves FIRST (Node\n      // runs the most-recently-registered hook first): on CUDA-13 hosts it\n      // redirects onnxruntime-node to the system-matched build before\n      // transformers imports it. No-op on matching layouts, non-CUDA,\n      // Windows/DirectML, and macOS. Mirrors the core embedder's call site so\n      // MCP query-time embedding gets the same CUDA-13 fix.\n      ensureOnnxRuntimeNodeMatchesSystem();\n      // The stack is an optionalDependency: npm prunes it when onnxruntime-node's\n      // postinstall can't reach api.nuget.org (#2370). Rethrow with actionable\n      // reinstall guidance instead of a raw ERR_MODULE_NOT_FOUND.\n      const { pipeline, env } = await import('@huggingface/transformers').catch((err: unknown) => {\n        const missing = getMissingLocalEmbeddingStackMessage(err);\n        if (missing) throw new Error(missing);\n        throw err;\n      });\n\n      env.allowLocalModels = false;\n      // Bridge user-controlled env vars to transformers.js: HF_HOME →\n      // env.cacheDir, HF_ENDPOINT → env.remoteHost (#1205). Centralised in\n      // applyHfEnvOverrides so this MCP entry point behaves identically to\n      // the analyze pipeline embedder.\n      applyHfEnvOverrides(env);\n      const embeddingConfig = resolveEmbeddingConfig();\n\n      logger.info('GitNexus: Loading embedding model (first search may take a moment)...');\n\n      const devicesToTry: Array<'dml' | 'cuda' | 'cpu'> =\n        embeddingConfig.device === 'dml' || embeddingConfig.device === 'cuda'\n          ? [embeddingConfig.device, 'cpu']\n          : ['cpu'];\n","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/mcp/core/embedder.ts#L76-L112","documentation":"During local embedder init, the dynamic import of @huggingface/transformers is wrapped so a module-not-found failure is rethrown as actionable guidance: the embedding stack is an optionalDependency that npm prunes when onnxruntime-node's postinstall cannot download CUDA support binaries from api.nuget.org (#2370). Everything except local embeddings still works; the message lists reinstall routes.","triggerScenarios":"Running `gitnexus analyze --embeddings` or MCP query-time embedding on an install where npm skipped the optional @huggingface/transformers / onnxruntime-node packages — typically because the postinstall NuGet download was blocked by an HTTP proxy, corporate firewall, or regional network restriction.","commonSituations":"Corporate machines behind egress proxies; installs in regions where api.nuget.org is slow/blocked; air-gapped or offline `npm install -g gitnexus`; Docker builds with restricted egress where the optional dep silently disappeared.","solutions":["Run `gitnexus embeddings install` — it fetches the stack on demand through your npm registry config (mirrors and proxies apply, no NuGet download); `gitnexus analyze --embeddings` runs it automatically.","On CUDA GPU hosts add --cuda, and behind a proxy also set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download.","Or reinstall with the CUDA download skipped since CPU embeddings need no CUDA: `ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus` (Windows: set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus).","Or point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to embed over HTTP."],"exampleFix":"# before: optional stack pruned during install\n$ gitnexus analyze --embeddings\n# → 'optional embedding stack is not installed' error\n\n# after: fetch the stack on demand (CPU-only, no NuGet needed)\n$ gitnexus embeddings install\n$ gitnexus analyze --embeddings\n\n# alternative: reinstall while skipping the CUDA download\n$ ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus","handlingStrategy":"validation","validationCode":"// Probe for the optional stack before enabling local embeddings\nasync function embeddingStackInstalled(): Promise<boolean> {\n  try {\n    await import('@huggingface/transformers');\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nif (wantLocalEmbeddings && !(await embeddingStackInstalled())) {\n  await exec('gitnexus embeddings install'); // or advise the user instead of failing later\n}","typeGuard":null,"tryCatchPattern":"try {\n  await initEmbedder();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('optional embedding stack is not installed')) {\n    // deterministic install gap: run the installer, then retry once\n    await exec('gitnexus embeddings install');\n    return initEmbedder();\n  }\n  throw err;\n}","preventionTips":["After installing/upgrading gitnexus behind a proxy, run `gitnexus embeddings install` proactively.","Use ONNXRUNTIME_NODE_INSTALL=skip for CPU-only installs to avoid the NuGet download entirely.","Configure npm mirrors/proxies so optionalDependencies survive install.","In Dockerfiles, add a verification step that imports @huggingface/transformers when embeddings are expected."],"tags":["embeddings","optional-dependencies","npm","onnxruntime","proxy","install"],"backgroundTag":"optional-dependency-not-installed","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}