abhigyanpatwari/GitNexus · error

runtimeBlocker (local embedding runtime blocker message)

Error message

runtimeBlocker (local embedding runtime blocker message)

What it means

spawnAndInit is the local embedding sidecar bootstrap. Before spawning the sidecar process it asks getLocalEmbeddingRuntimeBlocker() whether the local inference runtime (e.g. node-llama-cpp native module) is usable; if not, the blocking reason string is thrown verbatim as an Error. This fail-fast check prevents attempting to spawn a sidecar that cannot embed.

Solutions

1. Read the thrown message: it names the exact runtime blocker (missing module, unsupported platform, etc.) and address that specific condition first.
2. Reinstall dependencies so native runtime prebuilds are fetched/built: rm -rf node_modules && npm install with a working C/C++ toolchain available.
3. Verify the platform/arch/Node version are supported by the local embedding runtime; upgrade Node or switch to a supported platform.
4. If local embeddings are not required, configure an HTTP embedding endpoint instead so the sidecar path is never used.

Example fix

// before: relying on default local embeddings
const vectors = await embedBatch(items);
// after: guard the sidecar path / fall back to HTTP client
try {
  const vectors = await embedBatch(items);
} catch (e) {
  // runtime blocker: switch to remote embedding provider
  const vectors = await httpEmbedBatch(items, { endpoint: process.env.EMBED_URL });
}

// before using local embeddings
import { getLocalEmbeddingRuntimeBlocker } from './embedding-sidecar-client';
const blocker = getLocalEmbeddingRuntimeBlocker();
if (blocker) console.warn('Local embeddings unavailable:', blocker); // route to HTTP client
const useLocal = blocker === null;

try {
  vectors = await embedBatch(items);
} catch (e) {
  if (e instanceof Error && /runtime|blocker|platform|module/i.test(e.message)) {
    vectors = await httpEmbedBatch(items, { url: process.env.EMBED_URL });
  } else throw e;
}

When it happens

Trigger: Calling ensureEmbeddingSidecar() when the local embedding runtime is blocked — missing/incompatible native binaries, unsupported platform/arch, or the runtime module failed to load — getLocalEmbeddingRuntimeBlocker() returns a non-null reason and spawnAndInit throws it.

Common situations: Installing the package on an unsupported platform (e.g. Alpine musl, win32-arm64), a Node version incompatible with the prebuilt native runtime, a truncated npm install that skipped postinstall builds, or a Docker image missing glibc/libc++ needed by the local runtime.

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

• Local embeddings are unavailable after the sidecar aborted
• response.message (sidecar embed error)
• response.message (sidecar init error)
• analyze --watch does not support
• analyze --watch does not support

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

Appendix: source

Thrown at gitnexus/src/core/embeddings/embedding-sidecar-client.ts:306

export const getSidecarDevice = (): EmbeddingSidecarDevice | null => (ready ? device : null);

type EnsureSidecarOptions = {
  onProgress?: (progress: ModelProgress) => void;
  embeddingConfig?: Partial<EmbeddingConfig>;
  forceDevice?: EmbeddingSidecarDevice;
  signal?: AbortSignal;
};

const markUnavailableIfBudgetSpent = (): void => {
  if (deathSeen && recreatesUsed >= MAX_RECREATES) {
    localUnavailable = true;
  }
};

const spawnAndInit = async (options?: EnsureSidecarOptions): Promise<void> => {
  const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();
  if (runtimeBlocker) {
    throw new Error(runtimeBlocker);
  }
  markUnavailableIfBudgetSpent();
  if (localUnavailable) throw localUnavailableError();

  if (deathSeen) {
    recreatesUsed += 1;
    deathSeen = false;
  }

  const persisted = {
    embeddingConfig: options?.embeddingConfig ?? lastInitOptions?.embeddingConfig,
    forceDevice: options?.forceDevice ?? lastInitOptions?.forceDevice,
  };

  child = spawnSidecar();
  attachChild(child);
  progressSink = options?.onProgress;
  try {

View on GitHub (pinned to ac9a4e9abd)