abhigyanpatwari/GitNexus · error

Local semantic embeddings are unavailable: the optional…

Error message

Local semantic embeddings are unavailable: the optional embedding stack is not installed.
npm skipped the optional packages @huggingface/transformers / onnxruntime-node
during install — usually because onnxruntime-node's postinstall could not
download its CUDA support binaries from api.nuget.org (common behind HTTP
proxies and regional firewalls, #2370). Everything except local embeddings
still works.

To enable local embeddings:
  - Run `gitnexus embeddings install` — fetches the stack on demand through
    your npm registry config (mirrors and proxies apply; no NuGet download).
    `gitnexus analyze --embeddings` does this automatically.
    Add --cuda on CUDA GPU hosts (behind a proxy, also set
    GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download).
  - Or reinstall with the CUDA download skipped (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.

What it means

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.

Solutions

  1. 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.
  2. Add --cuda on CUDA GPU hosts; behind a proxy also set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download.
  3. Reinstall with the CUDA download skipped (CPU embeddings need no CUDA): ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus.
  4. Or switch to HTTP embeddings via GITNEXUS_EMBEDDING_URL (+ GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible endpoint.

Example fix

# before
npx gitnexus analyze --embeddings
# Local semantic embeddings are unavailable: the optional embedding stack is not installed...

# after (pick one)
gitnexus embeddings install && npx gitnexus analyze --embeddings
# or: ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus
# or: export GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1/embeddings GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small
Defensive patterns

Strategy: fallback

Validate before calling

// Detect the pruned optional stack before first use:
async function localEmbeddingStackInstalled(): Promise<boolean> {
  const path = await import('node:path');
  try {
    const mod = path.dirname(require.resolve('@huggingface/transformers/package.json'));
    return mod.length > 0;
  } catch {
    return false;
  }
}

Try / catch

try {
  await analyze({ repo: '.', embeddings: true });
} catch (err) {
  if (err instanceof Error && err.message.includes('optional embedding stack is not installed')) {
    await run('gitnexus embeddings install'); // npm-registry based; proxies/mirrors apply
    return analyze({ repo: '.', embeddings: true });
  }
  throw err;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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

Appendix: source

Thrown at gitnexus/src/core/embeddings/embedder.ts:135

      // the most recent hook first): when the optional stack was pruned at
      // install time (#2370), its bare specifiers fall back to the on-demand
      // runtime prefix.
      ensureEmbeddingStackResolvable();
      // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
      // import is unresolvable; register the fallback resolver first (#307).
      ensureOnnxRuntimeCommonResolvable();
      // Registered AFTER the common fallback so this hook resolves FIRST (Node
      // runs the most-recently-registered hook first): on CUDA-13 hosts it
      // redirects onnxruntime-node (and its version-matched onnxruntime-common)
      // to the CUDA-13 build before transformers imports them. No-op on matching
      // layouts, non-CUDA, Windows/DirectML, and macOS.
      ensureOnnxRuntimeNodeMatchesSystem();
      // The stack is an optionalDependency: npm prunes it when onnxruntime-node's
      // postinstall can't reach api.nuget.org (#2370). Rethrow with actionable
      // reinstall guidance instead of a raw ERR_MODULE_NOT_FOUND.
      const { pipeline, env } = await import('@huggingface/transformers').catch((err: unknown) => {
        const missing = getMissingLocalEmbeddingStackMessage(err);
        if (missing) throw new Error(missing);
        throw err;
      });

      // Configure transformers.js environment
      env.allowLocalModels = false;
      // Bridge user-controlled env vars to transformers.js: HF_HOME →
      // env.cacheDir, HF_ENDPOINT → env.remoteHost (#1205). Centralised in
      // applyHfEnvOverrides so the MCP embedder entry point behaves
      // identically.
      applyHfEnvOverrides(env);

      const isDev = process.env.NODE_ENV === 'development';
      if (isDev) {
        logger.info(`🧠 Loading embedding model: ${finalConfig.modelId}`);
      }

      const progressCallback = onProgress
        ? (data: ProgressInfo) => {

View on GitHub (pinned to aac7515d2a)