{"record":{"id":"c6ac6446659b9d84","repo":"chroma-core/chroma","slug":"unsupported-architecture-on-linux-process-arch","errorCode":null,"errorMessage":"Unsupported architecture on Linux: ${process.arch}","messagePattern":"Unsupported architecture on Linux: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"clients/js/packages/chromadb/src/bindings.ts","lineNumber":20,"sourceCode":"const 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 {\n  throw new Error(`Unsupported platform: ${process.platform}`);\n}\n\nexport default binding;\n","sourceCodeStart":2,"sourceCodeEnd":35,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb/src/bindings.ts#L2-L35","documentation":"Thrown at module load time by the chromadb package's bindings loader when running on Linux with a process.arch that is neither arm64 nor x64. The package ships prebuilt Rust bindings only for linux-arm64-gnu and linux-x64-gnu, so 32-bit or exotic architectures cannot load a binding and the import fails immediately.","triggerScenarios":"import \"chromadb\" on armv7l (32-bit ARM, e.g. Raspberry Pi OS 32-bit), i686, s390x, or ppc64le Linux; Alpine musl setups that report gnu-incompatible toolchains are adjacent but usually fail with a different loader error; QEMU-emulated containers reporting unusual arch.","commonSituations":"Deploying to Raspberry Pi or other 32-bit ARM boards; Docker images built with unusual base architectures; corporate mainframe/PPC environments; WSL setups with mismatched binaries.","solutions":["Run on a 64-bit x64 or arm64 Linux environment (e.g. upgrade Raspberry Pi OS to the 64-bit image).","Switch to the pure-JS client (chromadb-core or chromadb-cloud packages) which needs no native binding.","If you must stay on this arch, talk to a remote Chroma server over HTTP with the JS client instead of local native embeddings."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (process.platform === \"linux\" && !(process.arch === \"arm64\" || process.arch === \"x64\")) {\n  throw new Error(`No chromadb native binding for linux/${process.arch}; use the pure-JS client`);\n}\nconst { ChromaClient } = await import(\"chromadb\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Deploy on 64-bit x64/arm64 Linux images (e.g. 64-bit Raspberry Pi OS).","Add a startup platform assertion in apps that pull in native bindings transitively.","Prefer the HTTP (pure-JS) client against a remote Chroma server on constrained hardware."],"tags":["native-bindings","platform","linux","arm","module-load"],"backgroundTag":"unsupported-platform-architecture","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}