abhigyanpatwari/GitNexus · error

Local semantic embeddings are unavailable on macOS Intel…

Error message

Local semantic embeddings are unavailable on macOS Intel (darwin/x64).
The bundled ONNX Runtime package (onnxruntime-node) does not ship a
darwin/x64 native binding, so the local embedding model cannot load here.
ONNX_WEB_BACKEND=wasm does not help: the failure happens while importing
the native runtime, before any backend can be selected. Forcing
GITNEXUS_EMBEDDING_DEVICE=wasm (or cpu) does not help either, for the same reason.

Use one of these instead:
  - 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 GitNexus on Apple Silicon (darwin/arm64), which ships a binding.
  - Use a future GitNexus build that restores darwin/x64 ONNX support.

What it means

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.

Solutions

  1. Run analyze without --embeddings — all other indexing still works.
  2. Point GITNEXUS_EMBEDDING_URL (+ GITNEXUS_EMBEDDING_MODEL) at an OpenAI-compatible /v1/embeddings endpoint to embed over HTTP.
  3. Run GitNexus on Linux or in Docker, where the native binding ships.
  4. Move to Apple Silicon (darwin/arm64), which ships a binding, or await a future build that restores darwin/x64 ONNX support.

Example fix

# before (Intel Mac)
export GITNEXUS_EMBEDDING_DEVICE=wasm   # does not help
npx gitnexus analyze --embeddings
# Local semantic embeddings are unavailable on macOS Intel (darwin/x64)...

# after: HTTP embeddings, or skip local stack
export GITNEXUS_EMBEDDING_URL=https://api.openai.com/v1/embeddings
export GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small
npx gitnexus analyze --embeddings
# or simply: npx gitnexus analyze
Defensive patterns

Strategy: fallback

Validate before calling

// Pre-flight the platform before attempting local embeddings:
function localEmbeddingsSupportedHere(): boolean {
  const { platform, arch } = process;
  return !(platform === 'darwin' && arch === 'x64');
}
if (!localEmbeddingsSupportedHere() && !process.env.GITNEXUS_EMBEDDING_URL) {
  throw new Error('Use HTTP embeddings (GITNEXUS_EMBEDDING_URL) or skip --embeddings on macOS Intel');
}

Type guard

function isDarwinX64(): boolean {
  return process.platform === 'darwin' && process.arch === 'x64';
}

Try / catch

try {
  await analyze({ repo: '.', embeddings: true });
} catch (err) {
  if (err instanceof Error && err.message.includes('unavailable on macOS Intel')) {
    // fall back to indexing without embeddings — everything else still works
    return analyze({ repo: '.', embeddings: false });
  }
  throw err;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@aac7515d2a (2026-08-20). Data as JSON: /api/errors/e0c2d1fb75dbc812. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/embeddings/embedder.ts:88

  config: Partial<EmbeddingConfig> = {},
  forceDevice?: 'dml' | 'cuda' | 'cpu' | 'wasm',
): Promise<FeatureExtractionPipeline> => {
  if (isHttpMode()) {
    throw new Error(
      'initEmbedder() should not be called in HTTP mode. ' +
        'Use embedText()/embedBatch() which handle HTTP transparently.',
    );
  }

  // Fail fast on platforms where the bundled native ONNX Runtime binding is not
  // shipped (macOS Intel, #1515). Must run before any transformers.js /
  // onnxruntime-node import or resolution — otherwise the native module load
  // crashes with a raw "Cannot find module ...onnxruntime_binding.node" that
  // ONNX_WEB_BACKEND=wasm cannot rescue (#1516). HTTP mode was already handled
  // above, so this only blocks the local-runtime path.
  const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();
  if (runtimeBlocker) {
    throw new Error(runtimeBlocker);
  }

  // Return existing instance if available
  if (embedderInstance) {
    return embedderInstance;
  }

  // If already initializing, wait for that promise
  if (isInitializing && initPromise) {
    return initPromise;
  }

  isInitializing = true;

  const finalConfig = resolveEmbeddingConfig(config);
  // CUDA is probe-gated because ONNX Runtime can crash in native code when
  // provider libraries are missing. DirectML stays opt-in for the same reason.
  // Probe for CUDA first — ONNX Runtime crashes (uncatchable native error)

View on GitHub (pinned to aac7515d2a)