{"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":null,"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/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/core/embeddings/embedder.ts#L70-L106","documentation":"Before any transformers.js/onnxruntime-node import, the local embedder checks the platform: onnxruntime-node ships no darwin/x64 native binding, so on macOS Intel the local embedding model cannot load (#1515). The check runs early because the native module load crashes with a raw 'Cannot find module ...onnxruntime_binding.node' that ONNX_WEB_BACKEND=wasm or device forcing cannot rescue (#1516). HTTP embedding mode is handled before this point, so only the local path is blocked.","triggerScenarios":"Calling getOrCreateEmbedder() (directly or via analyze --embeddings without GITNEXUS_EMBEDDING_URL) on darwin/x64 (macOS Intel). getLocalEmbeddingRuntimeBlocker() returns the block message and it is thrown before any ONNX import is attempted.","commonSituations":"Intel Mac (or Intel-Managed Rosetta shell / x64 Node on Apple Silicon) users running --embeddings; CI images pinned to x64 macOS runners; teams where one developer on Intel Mac hits what ARM colleagues do not.","solutions":["Run analyze without --embeddings — all other indexing still works.","Point GITNEXUS_EMBEDDING_URL (+ 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.","Move to Apple Silicon (darwin/arm64), which ships a binding, or await a future build that restores darwin/x64 ONNX support."],"exampleFix":"# before (Intel Mac)\nexport GITNEXUS_EMBEDDING_DEVICE=wasm   # does not help\nnpx gitnexus analyze --embeddings\n# Local semantic embeddings are unavailable on macOS Intel (darwin/x64)...\n\n# after: HTTP embeddings, or skip local stack\nexport GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1/embeddings\nexport GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small\nnpx gitnexus analyze --embeddings\n# or simply: npx gitnexus analyze","handlingStrategy":"fallback","validationCode":"// Pre-flight the platform before attempting local embeddings:\nfunction localEmbeddingsSupportedHere(): boolean {\n  const { platform, arch } = process;\n  return !(platform === 'darwin' && arch === 'x64');\n}\nif (!localEmbeddingsSupportedHere() && !process.env.GITNEXUS_EMBEDDING_URL) {\n  throw new Error('Use HTTP embeddings (GITNEXUS_EMBEDDING_URL) or skip --embeddings on macOS Intel');\n}","typeGuard":"function isDarwinX64(): boolean {\n  return process.platform === 'darwin' && process.arch === 'x64';\n}","tryCatchPattern":"try {\n  await analyze({ repo: '.', embeddings: true });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('unavailable on macOS Intel')) {\n    // fall back to indexing without embeddings — everything else still works\n    return analyze({ repo: '.', embeddings: false });\n  }\n  throw err;\n}","preventionTips":["On Intel Macs, use GITNEXUS_EMBEDDING_URL HTTP embeddings or omit --embeddings; do not waste time on device/wasm forcing.","Check uname -m / process.arch in setup scripts before opting into local embeddings.","Run x64 Node only when you must; on Apple Silicon use the arm64 build.","Standardize CI on Linux runners when embeddings are required."],"tags":["embeddings","platform-support","macos-intel","onnxruntime","native-module"],"backgroundTag":"unsupported-platform","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}