{"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":"Error","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/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/embedder.ts#L117-L153","documentation":"Thrown by initEmbedder() when the dynamic `import('@huggingface/transformers')` rejects with ERR_MODULE_NOT_FOUND and getMissingLocalEmbeddingStackMessage() recognizes it. @huggingface/transformers and onnxruntime-node are optionalDependencies; npm prunes them when onnxruntime-node's postinstall cannot reach api.nuget.org to fetch CUDA support binaries (common behind HTTP proxies and regional firewalls, #2370). The raw module-not-found error is replaced with actionable reinstall guidance.","triggerScenarios":"First local-embedding run after an install where the optional stack was pruned. Typically behind a corporate proxy, in mainland China (NuGet blocked), or after ONNXRUNTIME_NODE_INSTALL=skip was set without intending to disable embeddings. Does not fire in HTTP mode or on macOS Intel (the platform blocker fires first).","commonSituations":"npm install -g gitnexus behind a proxy that blocks api.nuget.org; air-gapped network; an npm registry mirror that does not proxy the optional packages; installing with --omit=optional.","solutions":["Run `gitnexus embeddings install` — fetches the stack on demand through your npm registry config (mirrors/proxies apply; no NuGet download). `gitnexus analyze --embeddings` does this automatically.","On CUDA GPU hosts, add --cuda (and 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.","Point GITNEXUS_EMBEDDING_URL (+ GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to embed over HTTP instead of locally."],"exampleFix":"# before — stack pruned at install, local embeddings unavailable\n$ npx gitnexus analyze --embeddings\n# after — fetch the stack on demand through your npm registry\n$ npx gitnexus embeddings install\n$ npx gitnexus analyze --embeddings","handlingStrategy":"fallback","validationCode":"import { resolveEmbeddingRuntime } from 'gitnexus/src/core/embeddings/runtime-install.js';\n// Probe whether the optional stack is resolvable before calling initEmbedder.\ntry {\n  resolveEmbeddingRuntime(); // throws/resolves paths without loading native code\n} catch {\n  console.error('Optional embedding stack missing. Run `gitnexus embeddings install`.');\n}","typeGuard":"const isOptionalStackInstalled = async (): Promise<boolean> => {\n  try {\n    await import('@huggingface/transformers');\n    return true;\n  } catch {\n    return false;\n  }\n};","tryCatchPattern":"try {\n  await initEmbedder();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('optional embedding stack is not installed')) {\n    console.error('Run `gitnexus embeddings install` and retry, or use GITNEXUS_EMBEDDING_URL.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Run `gitnexus embeddings install` after installing gitnexus behind a proxy.","Set ONNXRUNTIME_NODE_INSTALL=skip during install only if you intend CPU-only embeddings.","Use GITNEXUS_EMBEDDING_URL for HTTP embeddings to avoid the optional native stack."],"tags":["install","optional-dependency","embeddings","network","onnxruntime"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}