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

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.

Source

Thrown at gitnexus/src/mcp/core/embedder.ts:94

      // 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 to the system-matched build before
      // transformers imports it. No-op on matching layouts, non-CUDA,
      // Windows/DirectML, and macOS. Mirrors the core embedder's call site so
      // MCP query-time embedding gets the same CUDA-13 fix.
      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;
      });

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

      logger.info('GitNexus: Loading embedding model (first search may take a moment)...');

      const devicesToTry: Array<'dml' | 'cuda' | 'cpu'> =
        embeddingConfig.device === 'dml' || embeddingConfig.device === 'cuda'
          ? [embeddingConfig.device, 'cpu']
          : ['cpu'];

View on GitHub (pinned to aac7515d2a)

Solutions

1. 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.
2. On CUDA GPU hosts add --cuda, and behind a proxy also set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> for the NuGet download.
3. 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).
4. Or point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to embed over HTTP.

Example fix

# before: optional stack pruned during install
$ gitnexus analyze --embeddings
# → 'optional embedding stack is not installed' error

# after: fetch the stack on demand (CPU-only, no NuGet needed)
$ gitnexus embeddings install
$ gitnexus analyze --embeddings

# alternative: reinstall while skipping the CUDA download
$ ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus

// Probe for the optional stack before enabling local embeddings
async function embeddingStackInstalled(): Promise<boolean> {
  try {
    await import('@huggingface/transformers');
    return true;
  } catch {
    return false;
  }
}

if (wantLocalEmbeddings && !(await embeddingStackInstalled())) {
  await exec('gitnexus embeddings install'); // or advise the user instead of failing later
}

try {
  await initEmbedder();
} catch (err) {
  if (err instanceof Error && err.message.includes('optional embedding stack is not installed')) {
    // deterministic install gap: run the installer, then retry once
    await exec('gitnexus embeddings install');
    return initEmbedder();
  }
  throw err;
}

When it happens

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

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

Related errors

• Local semantic embeddings are unavailable: the optional embe
• Local semantic embeddings are unavailable on macOS Intel (da
• No suitable device found for embedding model
• Local semantic embeddings are unavailable on macOS Intel (da
• Failed to load embedding model

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