abhigyanpatwari/GitNexus · error

runtimeBlocker (local embedding runtime blocker message)

Error message

runtimeBlocker (local embedding runtime blocker message)

What it means

initEmbedder throws the message produced by getLocalEmbeddingRuntimeBlocker() when local embedding is fundamentally unsupported on the current platform. The best-known case is macOS Intel (darwin/x64), where onnxruntime-node is unavailable so no local ONNX runtime can run. The message enumerates alternatives: skip --embeddings, use an HTTP embedding endpoint, or move to Linux/Apple Silicon.

Solutions

1. Run analyze without --embeddings (all other indexing still works).
2. Set GITNEXUS_EMBEDDING_URL (plus GITNEXUS_EMBEDDING_MODEL) to an OpenAI-compatible /v1/embeddings endpoint and embed over HTTP.
3. Run on Linux or Apple Silicon (darwin/arm64) and run `gitnexus embeddings install`.
4. For Docker, bind-mount a runtime prefix or use the HTTP embedding mode.

Example fix

// before: blocked locally on macOS Intel
npx gitnexus analyze --embeddings
// after: embed via a remote OpenAI-compatible endpoint
GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1 \
GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small \
npx gitnexus analyze --embeddings

import { getLocalEmbeddingRuntimeBlocker } from 'gitnexus/src/core/embeddings/runtime-support.js';
const blocker = getLocalEmbeddingRuntimeBlocker();
if (blocker) console.warn('local embeddings unavailable:', blocker.split('\n')[0]);

try {
  await initEmbedder();
} catch (err) {
  if (isLocalEmbeddingRuntimeBlockerMessage(err.message)) {
    // switch to HTTP embedding endpoint
  }
}

When it happens

Trigger: Calling initEmbedder() (or any code path that initializes the local embedder, e.g. `gitnexus analyze --embeddings`) on a platform where getLocalEmbeddingRuntimeBlocker() returns a blocker string — notably darwin/x64, where even GITNEXUS_EMBEDDING_DEVICE=wasm|cpu cannot help.

Common situations: Developers on Intel Macs running `analyze --embeddings`; official GitNexus Docker images that no longer ship onnxruntime-node; CI runners on unsupported platform/arch combos.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• runtimeBlocker (local embedding runtime blocker message)
• No suitable device found for embedding model
• assessment.message (local embedding runtime…
• Could not install the embedding runtime
• Could not verify persisted embedding count.

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

Appendix: source

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

  if (isHttpMode()) return null;
  return getSidecarDevice();
};

export const initEmbedder = async (
  onProgress?: ModelProgressCallback,
  config: Partial<EmbeddingConfig> = {},
  forceDevice?: EmbeddingSidecarDevice,
): Promise<{ device: EmbeddingSidecarDevice }> => {
  if (isHttpMode()) {
    throw new Error(
      'initEmbedder() should not be called in HTTP mode. ' +
        'Use embedText()/embedBatch() which handle HTTP transparently.',
    );
  }

  const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();
  if (runtimeBlocker) {
    throw new Error(runtimeBlocker);
  }

  return ensureEmbeddingSidecar({
    onProgress,
    embeddingConfig: config,
    forceDevice,
  });
};

export const getEmbedder = (): never => {
  if (isHttpMode()) {
    throw new Error(
      'getEmbedder() is not available in HTTP embedding mode. Use embedText()/embedBatch() instead.',
    );
  }
  throw new Error(
    'getEmbedder() is not available. Local inference runs in the embedding sidecar. Use embedText()/embedBatch() instead.',
  );

View on GitHub (pinned to ac9a4e9abd)