{"record":{"id":"cda151c1d152087d","repo":"abhigyanpatwari/GitNexus","slug":"local-semantic-embeddings-are-unavailable-on-macos-cda151","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/mcp/core/embedder.ts","lineNumber":57,"sourceCode":"let isInitializing = false;\nlet initPromise: Promise<FeatureExtractionPipeline> | null = null;\n\n/**\n * Initialize the embedding model (lazy, on first search)\n */\nexport const initEmbedder = async (): Promise<FeatureExtractionPipeline> => {\n  if (isHttpMode()) {\n    throw new Error('initEmbedder() should not be called in HTTP mode.');\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).\n  const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();\n  if (runtimeBlocker) {\n    throw new Error(runtimeBlocker);\n  }\n\n  if (embedderInstance) {\n    return embedderInstance;\n  }\n\n  if (isInitializing && initPromise) {\n    return initPromise;\n  }\n\n  isInitializing = true;\n\n  initPromise = (async () => {\n    try {\n      // Lazy-load transformers.js only after the runtime guard has passed, so\n      // unsupported platforms never reach the native ONNX import (#1515).\n      // Registered FIRST so it sits last in the hook chain (registerHooks runs\n      // the most recent hook first): when the optional stack was pruned at","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/mcp/core/embedder.ts#L39-L75","documentation":"initEmbedder fails fast when getLocalEmbeddingRuntimeBlocker() reports that the current platform (macOS Intel, darwin/x64) has no bundled onnxruntime-node native binding (#1515/#1516). The check runs before any transformers.js/onnxruntime-node import so the user gets structured guidance instead of a raw 'Cannot find module ...onnxruntime_binding.node' crash that no backend selection (ONNX_WEB_BACKEND=wasm, GITNEXUS_EMBEDDING_DEVICE) can rescue.","triggerScenarios":"Running `gitnexus analyze --embeddings`, or any MCP query-time semantic search that initializes the local embedder, on an Intel Mac (darwin/x64). The throw happens unconditionally on that platform regardless of env-var overrides.","commonSituations":"Teams on Intel MacBooks discovering semantic search fails after upgrading; CI jobs pinned to macos-13 (x64) runners while local devs are on Apple Silicon; Docker-averse users trying to enable --embeddings locally; users following docs that assume darwin/arm64.","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 binding.","Track for a future GitNexus build that restores darwin/x64 ONNX support."],"exampleFix":"# before: local embeddings on Intel macOS\n$ gitnexus analyze --embeddings\n# → long 'unavailable on macOS Intel (darwin/x64)' error\n\n# after: HTTP embeddings via an OpenAI-compatible endpoint\n$ export GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1/embeddings\n$ export GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small\n$ export GITNEXUS_EMBEDDING_API_KEY=sk-...\n$ gitnexus analyze --embeddings","handlingStrategy":"validation","validationCode":"// Gate embeddings on platform before invoking any embedding feature\nfunction localEmbeddingsSupported(): boolean {\n  const { platform, arch } = process;\n  return !(platform === 'darwin' && arch === 'x64'); // darwin/x64 ships no onnxruntime-node binding\n}\n\nconst useEmbeddings = flags.embeddings && localEmbeddingsSupported();\nconst useHttp = Boolean(process.env.GITNEXUS_EMBEDDING_URL);","typeGuard":null,"tryCatchPattern":"try {\n  await runAnalyze({ embeddings: true });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('unavailable on macOS Intel')) {\n    // platform limitation, retrying cannot help: continue without embeddings or switch to HTTP mode\n    await runAnalyze({ embeddings: false });\n    return;\n  }\n  throw err;\n}","preventionTips":["Detect darwin/x64 up front and default --embeddings off for those developers.","Standardize on the HTTP embedding route (GITNEXUS_EMBEDDING_URL/MODEL) for mixed-fleet teams.","Run embedding workloads in Docker/Linux CI rather than Intel macOS runners.","Do not burn time on ONNX_WEB_BACKEND / GITNEXUS_EMBEDDING_DEVICE workarounds — the import itself fails on this platform."],"tags":["embeddings","macos-intel","darwin-x64","onnxruntime","platform-support","native-module"],"backgroundTag":"native-module-platform-unsupported","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}