{"record":{"id":"56b5683517e890bd","repo":"abhigyanpatwari/GitNexus","slug":"local-embeddings-are-unavailable-after-the-sidecar-aborted","errorCode":null,"errorMessage":"Local embeddings are unavailable after the sidecar aborted","messagePattern":"Local embeddings are unavailable after the sidecar aborted","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/embedding-sidecar-client.ts","lineNumber":309,"sourceCode":"  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 {\n    const response = await request(\n      {\n        type: 'init',","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/embeddings/embedding-sidecar-client.ts#L291-L327","documentation":"This error is thrown by the internal spawnAndInit step of the embedding sidecar client. The sidecar child process previously died in a way indicating a native abort (SIGSEGV/SIGABRT/SIGBUS/SIGILL) or had already exhausted the single recreate attempt (MAX_RECREATES = 1), so the client latches `localUnavailable` and permanently refuses to spawn a new sidecar for this process lifetime. It prevents repeated crashes from an ONNX runtime or native binary that is fundamentally broken in this environment.","triggerScenarios":"Calling ensureEmbeddingSidecar (directly or via sidecarEmbedBatch) after a prior sidecar died with a native abort signal, or after the sidecar died once, was recreated once, and died again — markUnavailableIfBudgetSpent() sets localUnavailable and line 309 throws on the next spawn attempt.","commonSituations":"Broken or mismatched onnxruntime-node native binaries; CPU without required instruction sets (e.g. AVX) for the model runtime; sidecar killed by the OS (OOM/segfault) during model download or inference; GPU/CUDA library conflicts when forceDevice was requested.","solutions":["Restart the GitNexus process — the `localUnavailable` latch is in-memory only, so a fresh process clears it (after fixing the underlying crash cause).","Check sidecar stderr in debug logs for the native crash signature; reinstall or update onnxruntime-node / the model runtime so the native binary matches the platform.","Use a remote embedding provider instead of local embeddings (e.g. configure GITNEXUS_EMBEDDING_URL or an API-based provider) to bypass the sidecar entirely.","If the crash came from the device choice, retry with a different device (e.g. force CPU instead of GPU) once the process has been restarted.","Free memory or raise container limits if the abort correlates with model loading OOM."],"exampleFix":"// before: retrying embed calls in a process where the sidecar already aborted\nconst vectors = await sidecarEmbedBatch(texts); // throws forever\n// after: check device availability first and fall back to a remote provider\nif (getSidecarDevice() === null) {\n  const vectors = await remoteEmbedBatch(texts);\n} else {\n  const vectors = await sidecarEmbedBatch(texts);\n}","handlingStrategy":"fallback","validationCode":"// check local runtime availability before requesting local embeddings\nimport { getLocalEmbeddingRuntimeBlocker } from './runtime-support.js';\nconst blocker = getLocalEmbeddingRuntimeBlocker();\nif (blocker) useRemoteEmbeddings();","typeGuard":"// narrow to a sidecar-capable state\nconst canEmbedLocally = (): boolean => getSidecarDevice() !== null;","tryCatchPattern":"try {\n  await sidecarInit();\n} catch (err) {\n  if (String(err.message).includes('sidecar aborted')) {\n    logger.error('Local embeddings permanently unavailable; switching to remote provider');\n    enableRemoteEmbeddings();\n  } else {\n    throw err;\n  }\n}","preventionTips":["Pin onnxruntime-node versions and test sidecar startup in CI containers","Avoid forcing a GPU device unless the target host has working CUDA libs","Monitor sidecar stderr logs for native crash signatures before they latch the flag"],"tags":["embeddings","sidecar","native-crash","onnx","process-lifecycle"],"backgroundTag":"module-init-failed","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"}