chroma-core/chroma · critical

Unsupported architecture on macOS: ${process.arch}

Error message

Unsupported architecture on macOS: ${process.arch}

What it means

Thrown at module load time by the chromadb package's bindings loader. This package ships prebuilt Rust native bindings as optional platform/arch packages, and at import time it require()s the one matching process.platform and process.arch. On macOS only arm64 and x64 bindings exist, so any other architecture value fails immediately with this error. It occurs during import, before any Chroma code runs.

Source

Thrown at clients/js/packages/chromadb/src/bindings.ts:12

import { createRequire } from "module";
const require = createRequire(import.meta.url);

let binding: any;

if (process.platform === "darwin") {
  if (process.arch === "arm64") {
    binding = require("chromadb-js-bindings-darwin-arm64");
  } else if (process.arch === "x64") {
    binding = require("chromadb-js-bindings-darwin-x64");
  } else {
    throw new Error(`Unsupported architecture on macOS: ${process.arch}`);
  }
} else if (process.platform === "linux") {
  if (process.arch === "arm64") {
    binding = require("chromadb-js-bindings-linux-arm64-gnu");
  } else if (process.arch === "x64") {
    binding = require("chromadb-js-bindings-linux-x64-gnu");
  } else {
    throw new Error(`Unsupported architecture on Linux: ${process.arch}`);
  }
} else if (process.platform === "win32") {
  if (process.arch === "arm64") {
    binding = require("chromadb-js-bindings-win32-arm64-msvc");
  } else {
    throw new Error(
      `Unsupported Windows architecture: ${process.arch}. Only ARM64 is supported.`,
    );
  }
} else {

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Check process.arch in the failing environment; if it is not arm64 or x64, switch to a runtime that reports a supported arch.
2. Use the pure-JS client packages (chromadb-core / chromadb-cloud) which do not load native bindings.
3. If you are on Apple Silicon or Intel and still see this, verify your Node binary is an official arm64 or x64 build (uname -m, process.arch).

// Check before importing the native-bindings package
const supported =
  process.platform === "darwin" && (process.arch === "arm64" || process.arch === "x64");
if (!supported) {
  throw new Error(`chromadb native bindings unavailable on darwin/${process.arch}`);
}
const { ChromaClient } = await import("chromadb");

function supportsNativeBindings(platform: NodeJS.Platform, arch: string): boolean {
  if (platform === "darwin") return arch === "arm64" || arch === "x64";
  if (platform === "linux") return arch === "arm64" || arch === "x64";
  if (platform === "win32") return arch === "arm64";
  return false;
}

When it happens

Trigger: import "chromadb" (the native-bindings flavor) on macOS running an unusual process.arch such as a non-arm64/x64 Node build; running under a translated or emulated runtime that reports an unexpected process.arch; a custom-compiled Node that reports a different arch string.

Common situations: Experimental Node builds; container images with QEMU emulation reporting odd arch values; CI images that use exotic architectures. In practice rare on macOS because arm64 and x64 cover current Apple Silicon and Intel machines.

Related errors

• Unsupported architecture on Linux: ${process.arch}
• Unsupported Windows architecture: ${process.arch}. Only ARM6
• Unsupported platform: ${process.platform}
• Unsupported platform: ${platform}

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/2fbbdc5964e8b831. Report an issue: GitHub.