{"record":{"id":"4813328efa2422d5","repo":"chroma-core/chroma","slug":"unsupported-platform-platform","errorCode":null,"errorMessage":"Unsupported platform: ${platform}","messagePattern":"Unsupported platform: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"clients/new-js/packages/chromadb/src/bindings.ts","lineNumber":35,"sourceCode":"  }\n} else if (platform === \"linux\") {\n  if (arch === \"arm64\") {\n    binding = require(\"chromadb-js-bindings-linux-arm64-gnu\");\n  } else if (arch === \"x64\") {\n    binding = require(\"chromadb-js-bindings-linux-x64-gnu\");\n  } else {\n    throw new Error(`Unsupported architecture on Linux: ${arch}`);\n  }\n} else if (platform === \"win32\") {\n  if (arch === \"arm64\") {\n    binding = require(\"chromadb-js-bindings-win32-arm64-msvc\");\n  } else {\n    throw new Error(\n      `Unsupported Windows architecture: ${arch}. Only ARM64 is supported.`,\n    );\n  }\n} else {\n  throw new Error(`Unsupported platform: ${platform}`);\n}\n\nexport default binding;\n","sourceCodeStart":17,"sourceCodeEnd":39,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/bindings.ts#L17-L39","documentation":"Thrown at module load time by chromadb's native-binding resolver (src/bindings.ts). The package ships precompiled Rust native modules (chromadb-js-bindings-*) only for darwin x64/arm64, linux x64/arm64 (gnu), and win32 arm64; when os.platform() returns anything else (e.g. freebsd, openbsd, android, aix, sunos, haiku) there is no binary to require and the module throws immediately. This only affects the embedded (in-process) Chroma runtime, not the HTTP client.","triggerScenarios":"Importing or requiring the chromadb package (or anything that transitively pulls in src/bindings.ts) on a Node.js runtime whose os.platform() is not darwin, linux, or win32. Examples: FreeBSD/OpenBSD jails, Alpine on unusual kernels is fine (linux) but SmartOS/AIX/Android Termux (platform 'android') are not.","commonSituations":"Running Node inside a BSD container, a Termux/Android environment, or a niche CI image; importing the full chromadb package (rather than the client-only entry) in an environment the prebuilt binaries were never published for.","solutions":["Run the workload on a supported platform: macOS x64/arm64, Linux x64/arm64 (glibc), or Windows ARM64.","If you only need to talk to a Chroma server, avoid the embedded bindings entirely: use ChromaClient/CloudClient pointed at a running server URL instead of the embedded runtime.","For unsupported Unix systems, run chroma in Docker or as a separate server process and connect over HTTP from any platform.","If you must embed on an unsupported platform, build the Rust bindings from source for that target and alias the platform module."],"exampleFix":"// before (pulls in native bindings, fails on unsupported OS)\nimport { ChromaClient } from \"chromadb\"; // transitively loads src/bindings.ts on import of embedded entry\n\n// after (client-server mode, no native bindings needed)\nimport { ChromaClient } from \"chromadb\";\nconst client = new ChromaClient({ path: \"http://localhost:8000\" }); // talk to chroma server over HTTP","handlingStrategy":"validation","validationCode":"import os from \"os\";\nconst SUPPORTED = new Set([\n  \"darwin:arm64\", \"darwin:x64\",\n  \"linux:arm64\", \"linux:x64\",\n  \"win32:arm64\",\n]);\nconst key = `${os.platform()}:${os.arch()}`;\nif (!SUPPORTED.has(key)) {\n  throw new Error(`Embedded chromadb unsupported on ${key}; use client-server mode instead`);\n}\nawait import(\"chromadb\");","typeGuard":"const isSupportedPlatform = (): boolean =>\n  [\"darwin\", \"linux\", \"win32\"].includes(os.platform()) &&\n  !(os.platform() === \"win32\" && os.arch() !== \"arm64\");","tryCatchPattern":null,"preventionTips":["Pin CI/test images to macOS, Linux x64/arm64, or Windows ARM64 when the embedded runtime is required.","Prefer client-server mode (ChromaClient + chroma run / Docker) for portability across environments.","Check os.platform()/os.arch() at startup before importing the embedded entry point."],"tags":["native-bindings","platform-support","module-load","embedded"],"backgroundTag":"unsupported-platform-native-module","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}