{"record":{"id":"2fbbdc5964e8b831","repo":"chroma-core/chroma","slug":"unsupported-architecture-on-macos-process-arch","errorCode":null,"errorMessage":"Unsupported architecture on macOS: ${process.arch}","messagePattern":"Unsupported architecture on macOS: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"clients/js/packages/chromadb/src/bindings.ts","lineNumber":12,"sourceCode":"import { createRequire } from \"module\";\nconst require = createRequire(import.meta.url);\n\nlet binding: any;\n\nif (process.platform === \"darwin\") {\n  if (process.arch === \"arm64\") {\n    binding = require(\"chromadb-js-bindings-darwin-arm64\");\n  } else if (process.arch === \"x64\") {\n    binding = require(\"chromadb-js-bindings-darwin-x64\");\n  } else {\n    throw new Error(`Unsupported architecture on macOS: ${process.arch}`);\n  }\n} else if (process.platform === \"linux\") {\n  if (process.arch === \"arm64\") {\n    binding = require(\"chromadb-js-bindings-linux-arm64-gnu\");\n  } else if (process.arch === \"x64\") {\n    binding = require(\"chromadb-js-bindings-linux-x64-gnu\");\n  } else {\n    throw new Error(`Unsupported architecture on Linux: ${process.arch}`);\n  }\n} else if (process.platform === \"win32\") {\n  if (process.arch === \"arm64\") {\n    binding = require(\"chromadb-js-bindings-win32-arm64-msvc\");\n  } else {\n    throw new Error(\n      `Unsupported Windows architecture: ${process.arch}. Only ARM64 is supported.`,\n    );\n  }\n} else {","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb/src/bindings.ts#L1-L30","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check process.arch in the failing environment; if it is not arm64 or x64, switch to a runtime that reports a supported arch.","Use the pure-JS client packages (chromadb-core / chromadb-cloud) which do not load native bindings.","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)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check before importing the native-bindings package\nconst supported =\n  process.platform === \"darwin\" && (process.arch === \"arm64\" || process.arch === \"x64\");\nif (!supported) {\n  throw new Error(`chromadb native bindings unavailable on darwin/${process.arch}`);\n}\nconst { ChromaClient } = await import(\"chromadb\");","typeGuard":"function supportsNativeBindings(platform: NodeJS.Platform, arch: string): boolean {\n  if (platform === \"darwin\") return arch === \"arm64\" || arch === \"x64\";\n  if (platform === \"linux\") return arch === \"arm64\" || arch === \"x64\";\n  if (platform === \"win32\") return arch === \"arm64\";\n  return false;\n}","tryCatchPattern":null,"preventionTips":["Verify process.arch in CI matrices before adding the native chromadb package.","Keep a pure-JS fallback import path (chromadb-core) behind a platform check.","Use dynamic import() so the binding loads only after the platform check passes."],"tags":["native-bindings","platform","macos","module-load"],"backgroundTag":"unsupported-platform-architecture","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}