{"record":{"id":"e0c2d1fb75dbc812","repo":"abhigyanpatwari/GitNexus","slug":"local-semantic-embeddings-are-unavailable-on-macos","errorCode":null,"errorMessage":"Local semantic embeddings are unavailable on macOS Intel (darwin/x64).\nThe bundled ONNX Runtime package (onnxruntime-node) does not ship a\ndarwin/x64 native binding, so the local embedding model cannot load here.\nONNX_WEB_BACKEND=wasm does not help: the failure happens while importing\nthe native runtime, before any backend can be selected. Forcing\nGITNEXUS_EMBEDDING_DEVICE=wasm (or cpu) does not help either, for the same reason.\n\nUse one of these instead:\n  - Run analyze without --embeddings (all other indexing still works).\n  - Point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an\n    OpenAI-compatible /v1/embeddings endpoint to embed over HTTP.\n  - Run GitNexus on Linux or in Docker, where the native binding ships.\n  - Run GitNexus on Apple Silicon (darwin/arm64), which ships a binding.\n  - Use a future GitNexus build that restores darwin/x64 ONNX support.","messagePattern":"Local semantic embeddings are unavailable on macOS Intel \\(darwin/x64\\)\\.\nThe bundled ONNX Runtime package \\(onnxruntime-node\\) does not ship a\ndarwin/x64 native binding, so the local embedding model cannot load here\\.\nONNX_WEB_BACKEND=wasm does not help: the failure happens while importing\nthe native runtime, before any backend can be selected\\. Forcing\nGITNEXUS_EMBEDDING_DEVICE=wasm \\(or cpu\\) does not help either, for the same reason\\.\n\nUse one of these instead:\n  - Run analyze without --embeddings \\(all other indexing still works\\)\\.\n  - Point GITNEXUS_EMBEDDING_URL \\(with GITNEXUS_EMBEDDING_MODEL\\) at an\n    OpenAI-compatible /v1/embeddings endpoint to embed over HTTP\\.\n  - Run GitNexus on Linux or in Docker, where the native binding ships\\.\n  - Run GitNexus on Apple Silicon \\(darwin/arm64\\), which ships a binding\\.\n  - Use a future GitNexus build that restores darwin/x64 ONNX support\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/embedder.ts","lineNumber":88,"sourceCode":"  config: Partial<EmbeddingConfig> = {},\n  forceDevice?: 'dml' | 'cuda' | 'cpu' | 'wasm',\n): Promise<FeatureExtractionPipeline> => {\n  if (isHttpMode()) {\n    throw new Error(\n      'initEmbedder() should not be called in HTTP mode. ' +\n        'Use embedText()/embedBatch() which handle HTTP transparently.',\n    );\n  }\n\n  // Fail fast on platforms where the bundled native ONNX Runtime binding is not\n  // shipped (macOS Intel, #1515). Must run before any transformers.js /\n  // onnxruntime-node import or resolution — otherwise the native module load\n  // crashes with a raw \"Cannot find module ...onnxruntime_binding.node\" that\n  // ONNX_WEB_BACKEND=wasm cannot rescue (#1516). HTTP mode was already handled\n  // above, so this only blocks the local-runtime path.\n  const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();\n  if (runtimeBlocker) {\n    throw new Error(runtimeBlocker);\n  }\n\n  // Return existing instance if available\n  if (embedderInstance) {\n    return embedderInstance;\n  }\n\n  // If already initializing, wait for that promise\n  if (isInitializing && initPromise) {\n    return initPromise;\n  }\n\n  isInitializing = true;\n\n  const finalConfig = resolveEmbeddingConfig(config);\n  // CUDA is probe-gated because ONNX Runtime can crash in native code when\n  // provider libraries are missing. DirectML stays opt-in for the same reason.\n  // Probe for CUDA first — ONNX Runtime crashes (uncatchable native error)","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/embedder.ts#L70-L106","documentation":"Thrown by initEmbedder() when getLocalEmbeddingRuntimeBlocker() returns a non-null message, which happens exactly when process.platform==='darwin' && process.arch==='x64'. onnxruntime-node ships no darwin/x64 native binding, so importing transformers.js crashes with a raw 'Cannot find module ...onnxruntime_binding.node' before any device/backend selection can run. The blocker is checked before any native import so the user gets actionable guidance instead of a native crash; ONNX_WEB_BACKEND=wasm and GITNEXUS_EMBEDDING_DEVICE=wasm cannot help because the failure is at import time, not backend selection (#1515/#1516).","triggerScenarios":"Running `gitnexus analyze --embeddings` (or any path that calls initEmbedder) on an Intel Mac. HTTP mode is exempt — the guard runs only after the isHttpMode() early return, so setting GITNEXUS_EMBEDDING_URL bypasses this entirely.","commonSituations":"Developer on an Intel MacBook running local embeddings for the first time; CI on a macOS Intel GitHub Actions runner; trying ONNX_WEB_BACKEND=wasm or GITNEXUS_EMBEDDING_DEVICE=cpu/wasm in the hope of bypassing the native binding.","solutions":["Run analyze without --embeddings — all other indexing still works.","Point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to embed over HTTP.","Run GitNexus on Linux or in Docker, where the native binding ships.","Run on Apple Silicon (darwin/arm64), which ships a darwin/arm64 binding.","Use a future GitNexus build that restores darwin/x64 ONNX support."],"exampleFix":"# before — fails on Intel Mac\n$ npx gitnexus analyze --embeddings\n# after — route embeddings over HTTP instead\n$ export GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1/embeddings\n$ export GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small\n$ npx gitnexus analyze --embeddings","handlingStrategy":"validation","validationCode":"import { getLocalEmbeddingRuntimeBlocker } from 'gitnexus/src/core/embeddings/runtime-support.js';\nimport { isHttpMode } from 'gitnexus/src/core/embeddings/http-client.js';\n// Detect the macOS-Intel blocker before attempting local init.\nconst blocker = !isHttpMode() ? getLocalEmbeddingRuntimeBlocker() : null;\nif (blocker) {\n  console.error(blocker);\n  process.exit(1);\n}","typeGuard":"const isMacOsIntel = (): boolean =>\n  process.platform === 'darwin' && process.arch === 'x64';\nconst localEmbeddingsSupported = (): boolean => !isMacOsIntel();","tryCatchPattern":null,"preventionTips":["On Intel Macs, use HTTP mode (GITNEXUS_EMBEDDING_URL+MODEL) for embeddings.","Run analyze without --embeddings on Intel Macs — all other indexing works.","Do not set ONNX_WEB_BACKEND=wasm or GITNEXUS_EMBEDDING_DEVICE=wasm to bypass — it cannot help on darwin/x64."],"tags":["platform","macos-intel","onnxruntime","embeddings","native-binding"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}