{"record":{"id":"cfaf459be6c8369d","repo":"abhigyanpatwari/GitNexus","slug":"runtimeblocker-local-embedding-runtime-blocker-message-cfaf45","errorCode":null,"errorMessage":"runtimeBlocker (local embedding runtime blocker message)","messagePattern":"runtimeBlocker \\(local embedding runtime blocker message\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/embedding-sidecar-client.ts","lineNumber":306,"sourceCode":"export const getSidecarDevice = (): EmbeddingSidecarDevice | null => (ready ? device : null);\n\ntype EnsureSidecarOptions = {\n  onProgress?: (progress: ModelProgress) => void;\n  embeddingConfig?: Partial<EmbeddingConfig>;\n  forceDevice?: EmbeddingSidecarDevice;\n  signal?: AbortSignal;\n};\n\nconst markUnavailableIfBudgetSpent = (): void => {\n  if (deathSeen && recreatesUsed >= MAX_RECREATES) {\n    localUnavailable = true;\n  }\n};\n\nconst spawnAndInit = async (options?: EnsureSidecarOptions): Promise<void> => {\n  const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();\n  if (runtimeBlocker) {\n    throw new Error(runtimeBlocker);\n  }\n  markUnavailableIfBudgetSpent();\n  if (localUnavailable) throw localUnavailableError();\n\n  if (deathSeen) {\n    recreatesUsed += 1;\n    deathSeen = false;\n  }\n\n  const persisted = {\n    embeddingConfig: options?.embeddingConfig ?? lastInitOptions?.embeddingConfig,\n    forceDevice: options?.forceDevice ?? lastInitOptions?.forceDevice,\n  };\n\n  child = spawnSidecar();\n  attachChild(child);\n  progressSink = options?.onProgress;\n  try {","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/embeddings/embedding-sidecar-client.ts#L288-L324","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the thrown message: it names the exact runtime blocker (missing module, unsupported platform, etc.) and address that specific condition first.","Reinstall dependencies so native runtime prebuilds are fetched/built: rm -rf node_modules && npm install with a working C/C++ toolchain available.","Verify the platform/arch/Node version are supported by the local embedding runtime; upgrade Node or switch to a supported platform.","If local embeddings are not required, configure an HTTP embedding endpoint instead so the sidecar path is never used."],"exampleFix":"// before: relying on default local embeddings\nconst vectors = await embedBatch(items);\n// after: guard the sidecar path / fall back to HTTP client\ntry {\n  const vectors = await embedBatch(items);\n} catch (e) {\n  // runtime blocker: switch to remote embedding provider\n  const vectors = await httpEmbedBatch(items, { endpoint: process.env.EMBED_URL });\n}","handlingStrategy":"fallback","validationCode":"// before using local embeddings\nimport { getLocalEmbeddingRuntimeBlocker } from './embedding-sidecar-client';\nconst blocker = getLocalEmbeddingRuntimeBlocker();\nif (blocker) console.warn('Local embeddings unavailable:', blocker); // route to HTTP client\nconst useLocal = blocker === null;","typeGuard":null,"tryCatchPattern":"try {\n  vectors = await embedBatch(items);\n} catch (e) {\n  if (e instanceof Error && /runtime|blocker|platform|module/i.test(e.message)) {\n    vectors = await httpEmbedBatch(items, { url: process.env.EMBED_URL });\n  } else throw e;\n}","preventionTips":["Check getLocalEmbeddingRuntimeBlocker() at startup and log the reason once instead of failing mid-task.","Pin supported Node versions and platforms in CI/environments where local embeddings are used.","Run full npm install (not --ignore-scripts) so native runtime prebuilds are activated.","Configure a remote embedding endpoint as an always-available fallback."],"tags":["embeddings","local-runtime","sidecar","platform"],"backgroundTag":"unsupported-platform","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-09-15T23:29:44.066Z","contentChangedAt":"2026-09-15T23:29:44.066Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}