{"record":{"id":"b26015920e310973","repo":"abhigyanpatwari/GitNexus","slug":"local-semantic-embeddings-are-unavailable-the-opt","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":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/embedder.ts","lineNumber":135,"sourceCode":"      // the most recent hook first): when the optional stack was pruned at\n      // 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 (and its version-matched onnxruntime-common)\n      // to the CUDA-13 build before transformers imports them. No-op on matching\n      // layouts, non-CUDA, Windows/DirectML, and macOS.\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      // Configure transformers.js environment\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 the MCP embedder entry point behaves\n      // identically.\n      applyHfEnvOverrides(env);\n\n      const isDev = process.env.NODE_ENV === 'development';\n      if (isDev) {\n        logger.info(`🧠 Loading embedding model: ${finalConfig.modelId}`);\n      }\n\n      const progressCallback = onProgress\n        ? (data: ProgressInfo) => {","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/core/embeddings/embedder.ts#L117-L153","documentation":"The local embedding stack (@huggingface/transformers + onnxruntime-node) is an optionalDependency; npm prunes it when onnxruntime-node's postinstall cannot download CUDA support binaries from api.nuget.org — common behind HTTP proxies and regional firewalls (#2370). When the dynamic import of transformers fails, getMissingLocalEmbeddingStackMessage() recognizes the ERR_MODULE_NOT_FOUND shape and rethrows this actionable guidance instead of the raw error. Everything except local embeddings still works.","triggerScenarios":"Initializing local embeddings on an install where the optional stack was pruned: dynamic import('@huggingface/transformers') inside getOrCreateEmbedder() rejects with a module-not-found error, the helper classifies it, and this Error replaces the raw one.","commonSituations":"Corporate proxies blocking api.nuget.org, restricted regions, air-gapped installs, or npm config (omit/optional=false) pruning optional deps; the failure appears only when local embeddings are first used, not at install time.","solutions":["Run `gitnexus embeddings install` — fetches the stack on demand through your npm registry config (mirrors/proxies apply, no NuGet download); `gitnexus analyze --embeddings` also triggers it automatically.","Add --cuda on CUDA GPU hosts; behind a proxy also set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download.","Reinstall with the CUDA download skipped (CPU embeddings need no CUDA): ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus.","Or switch to HTTP embeddings via GITNEXUS_EMBEDDING_URL (+ GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible endpoint."],"exampleFix":"# before\nnpx gitnexus analyze --embeddings\n# Local semantic embeddings are unavailable: the optional embedding stack is not installed...\n\n# after (pick one)\ngitnexus embeddings install && npx gitnexus analyze --embeddings\n# or: ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus\n# or: export GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1/embeddings GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small","handlingStrategy":"fallback","validationCode":"// Detect the pruned optional stack before first use:\nasync function localEmbeddingStackInstalled(): Promise<boolean> {\n  const path = await import('node:path');\n  try {\n    const mod = path.dirname(require.resolve('@huggingface/transformers/package.json'));\n    return mod.length > 0;\n  } catch {\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await analyze({ repo: '.', embeddings: true });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('optional embedding stack is not installed')) {\n    await run('gitnexus embeddings install'); // npm-registry based; proxies/mirrors apply\n    return analyze({ repo: '.', embeddings: true });\n  }\n  throw err;\n}","preventionTips":["Run `gitnexus embeddings install` as an explicit provisioning step (it needs no NuGet access).","Behind blocking proxies, prefer ONNXRUNTIME_NODE_INSTALL=skip installs or HTTP embeddings.","Set GLOBAL_AGENT_HTTPS_PROXY when the CUDA postinstall must traverse a proxy.","Verify the stack after install: require.resolve('@huggingface/transformers') should succeed."],"tags":["embeddings","optional-dependencies","npm-install","proxy","onnxruntime"],"backgroundTag":"missing-optional-dependency","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}