abhigyanpatwari/GitNexus · error · Error

Local semantic embeddings are unavailable: the optional embe

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

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.

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 d540b00184)

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` does this automatically.
  2. On CUDA GPU hosts, add --cuda (and 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. Point GITNEXUS_EMBEDDING_URL (+ GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to embed over HTTP instead of locally.

Example fix

# before — stack pruned at install, local embeddings unavailable
$ npx gitnexus analyze --embeddings
# after — fetch the stack on demand through your npm registry
$ npx gitnexus embeddings install
$ npx gitnexus analyze --embeddings
Defensive patterns

Strategy: fallback

Validate before calling

import { resolveEmbeddingRuntime } from 'gitnexus/src/core/embeddings/runtime-install.js';
// Probe whether the optional stack is resolvable before calling initEmbedder.
try {
  resolveEmbeddingRuntime(); // throws/resolves paths without loading native code
} catch {
  console.error('Optional embedding stack missing. Run `gitnexus embeddings install`.');
}

Type guard

const isOptionalStackInstalled = async (): Promise<boolean> => {
  try {
    await import('@huggingface/transformers');
    return true;
  } catch {
    return false;
  }
};

Try / catch

try {
  await initEmbedder();
} catch (err) {
  if (err instanceof Error && err.message.includes('optional embedding stack is not installed')) {
    console.error('Run `gitnexus embeddings install` and retry, or use GITNEXUS_EMBEDDING_URL.');
    process.exit(1);
  }
  throw err;
}

Prevention

When it happens

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

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

Related errors

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