Could not install the embedding runtime

Error message

Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n${localEmbeddingStackMissingMessage()}

What it means

Thrown by embeddingsSyncCommand when the automatic on-demand installation of the local embedding runtime (onnxruntime-node / @huggingface/transformers into ~/.gitnexus/embedding-runtime) fails. The error wraps the underlying install failure message and appends actionable guidance (localEmbeddingStackMissingMessage) explaining how to enable local embeddings. It is a deliberate wrapper so users see a heal path instead of a raw npm/network error.

Solutions

Check network/registry access, then rerun the command — the install is retried automatically on next sync.
Run `gitnexus embeddings install` manually and watch the full error output.
If behind a proxy, set GLOBAL_AGENT_HTTPS_PROXY (and npm registry config) before installing; add --cuda on CUDA hosts.
Point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to skip the local runtime entirely.
If a leftover 1.6.12 install is present, do a clean reinstall of gitnexus (a --force refresh only updates prefix overrides).

Example fix

// before: sync fails in a sandboxed CI without registry access
npx gitnexus embeddings sync
// after: embed over HTTP instead of installing the local runtime
GITNEXUS_EMBEDDING_URL=https://api.example.com/v1 \
GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small \
npx gitnexus embeddings sync

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight before sync
import { assessLocalEmbeddingRuntime } from 'gitnexus/src/core/embeddings/runtime-support.js';
const a = assessLocalEmbeddingRuntime();
if (a.status === 'needs-install') console.log('runtime will auto-install; ensure registry access');

Try / catch

try {
  await embeddingsSyncCommand(...);
} catch (err) {
  if (String(err.message).startsWith('Could not install the embedding runtime')) {
    // fall back to HTTP embedding or instruct `gitnexus embeddings install`
  }
}

Prevention

Ensure npm registry and proxy env (GLOBAL_AGENT_HTTPS_PROXY) are configured before running sync
Run `gitnexus embeddings install` proactively after installing gitnexus
Use HTTP embedding (GITNEXUS_EMBEDDING_URL) in sandboxed/offline environments

When it happens

Trigger: Running `gitnexus embeddings sync` (or `analyze --embeddings`) when the local embedding stack is not installed and the call to installEmbeddingRuntime() rejects — e.g. npm registry unreachable, proxy misconfigured, GITNEXUS_EMBEDDING_RUNTIME_DIR unwritable, or the install times out (ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS).

Common situations: Fresh installs where the optional embedding stack was pruned from the default npm install; corporate proxies blocking the registry or NuGet download for CUDA; offline machines; a stale/partial ~/.gitnexus/embedding-runtime from a previous failed install.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at gitnexus/src/cli/embeddings-sync.ts:139

          'Run `gitnexus analyze --embeddings --force` to rebuild the column at the new width.',
      );
    }

    if (!isHttpMode()) {
      const assessment = assessLocalEmbeddingRuntime();
      if (assessment.status === 'blocked' || assessment.status === 'prefix-unloadable') {
        throw new Error(assessment.message);
      }
      if (assessment.status === 'needs-install') {
        cliInfo(`Local embedding runtime is not installed.`);
        cliInfo(`Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …`);
        try {
          await installEmbeddingRuntime(
            {},
            getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS),
          );
        } catch (err) {
          throw new Error(
            `Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n` +
              localEmbeddingStackMissingMessage(),
          );
        }
      }
    }

    await initLbug(lbugPath);
    try {
      const existing = await fetchExistingEmbeddingHashes(executeQuery);
      let lastPercent = -1;

      const countEmbeddings = async (): Promise<number | undefined> =>
        persistedEmbeddingCountOrUndefined(await measurePersistedEmbeddingCount(executeQuery));
      // One write path for every meta update this command makes. The re-read
      // happens immediately before each save so a concurrent writer's fields
      // survive. #2790 traced two production drifts to hand-copied writers of
      // these exact fields, so this file keeps one copy instead of three.

View on GitHub (pinned to ac9a4e9abd)