abhigyanpatwari/GitNexus · error

missing (message for missing local embedding stack packages)

Error message

missing (message for missing local embedding stack packages)

What it means

initLocalEmbedder converts an ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND failure from the dynamic import of @huggingface/transformers into the actionable missing-stack message from getMissingLocalEmbeddingStackMessage(). The default gitnexus npm install no longer ships the optional embedding packages, so importing them fails until the runtime prefix is installed. Unrelated module-not-found errors inside transformers.js are re-thrown unchanged.

Solutions

1. Run `gitnexus embeddings install` — fetches the stack into ~/.gitnexus/embedding-runtime (or GITNEXUS_EMBEDDING_RUNTIME_DIR).
2. On CUDA hosts add --cuda (and set GLOBAL_AGENT_HTTPS_PROXY behind a proxy) for the NuGet download.
3. If a leftover 1.6.12 package-first tree exists, do a clean reinstall of gitnexus; --force only refreshes prefix overrides.
4. Alternatively set GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL to embed over HTTP without the local stack.

Example fix

// before: import fails, stack pruned by default
const embedder = await initLocalEmbedder();
// after (shell)
gitnexus embeddings install && node -e "import('...').then(m => m.initLocalEmbedder())"

import { resolveEmbeddingRuntime, assessLocalEmbeddingRuntime } from 'gitnexus/src/core/embeddings/runtime-support.js';
if (assessLocalEmbeddingRuntime().status === 'needs-install') {
  console.log('Run `gitnexus embeddings install` first');
}

try {
  await initLocalEmbedder();
} catch (err) {
  if (isMissingLocalEmbeddingStackMessage(err.message)) {
    // instruct: gitnexus embeddings install, or fall back to GITNEXUS_EMBEDDING_URL
  } else throw err;
}

When it happens

Trigger: Calling initLocalEmbedder() when the local embedding stack is not installed (resolveEmbeddingRuntime found no prefix and the packages are absent from node_modules) and ensureEmbeddingStackResolvable/ensureOnnxRuntime* checks let a missing-specifier import() through, or the import itself fails with the package name in the error.

Common situations: Fresh `npm install gitnexus` without running `gitnexus embeddings install`; upgrading from 1.6.12 where packages were inlined and are now pruned; GITNEXUS_EMBEDDING_RUNTIME_DIR pointing at an empty/unpopulated directory.

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

• Could not install the embedding runtime
• Could not verify persisted embedding count.
• Failed to download embedding model
• gitnexus/package.json#version is missing or not a string —…
• GitNexus package version is unavailable in

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-15). Data as JSON: /api/errors/3a6c7782f12583ab. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/embeddings/embedding-local-init.ts:87

  }

  const finalConfig = resolveEmbeddingConfig(config);
  const gpuDevice: EmbeddingSidecarDevice = isEffectiveCudaAvailable()
    ? 'cuda'
    : process.platform === 'win32'
      ? 'dml'
      : 'cpu';
  const requestedDevice =
    forceDevice || (finalConfig.device === 'auto' ? gpuDevice : finalConfig.device);

  initPromise = (async () => {
    try {
      ensureEmbeddingStackResolvable();
      ensureOnnxRuntimeCommonResolvable();
      ensureOnnxRuntimeNodeMatchesSystem();
      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;
      applyHfEnvOverrides(env);

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

      const progressCallback = onProgress
        ? (data: ProgressInfo) => {
            const progress: ModelProgress = {
              status:
                data.status === 'progress_total'
                  ? 'progress'
                  : ((data.status as ModelProgress['status']) ?? 'progress'),

View on GitHub (pinned to ac9a4e9abd)