{"record":{"id":"051df1f8620abb92","repo":"JuliusBrussee/caveman","slug":"off-states-unsupportedplatform-os-arch-line","errorCode":null,"errorMessage":"OFF_STATES.unsupportedPlatform(os, arch).line","messagePattern":"OFF_STATES\\.unsupportedPlatform\\(os, arch\\)\\.line","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2220,"sourceCode":"const INSTALL_BINARIES = GO_BINARIES.map((binary) => binary.name);\n\nfunction setupTimeoutSeconds(): number {\n  const raw = process.env.CAVE_SETUP_TIMEOUT ?? \"300\";\n  const parsed = Number(raw);\n  if (!Number.isInteger(parsed) || parsed <= 0) {\n    throw new Error(`CAVE_SETUP_TIMEOUT must be a positive integer (got ${JSON.stringify(raw)})`);\n  }\n  return parsed;\n}\n\nexport function setupPlatform(\n  os: NodeJS.Platform = process.platform,\n  nodeArch: string = process.arch,\n): { os: string; arch: string } {\n  const arch = nodeArch === \"x64\" ? \"amd64\" : nodeArch;\n  if (!(os === \"darwin\" || os === \"linux\" || os === \"win32\") ||\n      !(arch === \"arm64\" || arch === \"amd64\")) {\n    throw new Error(OFF_STATES.unsupportedPlatform(os, arch).line);\n  }\n  return { os, arch };\n}\n\nexport function binaryInstallFilename(name: string, os: string = process.platform): string {\n  return os === \"win32\" ? `${name}.exe` : name;\n}\n\nfunction binaryInstallManifestPath(): string {\n  return join(cavemanHome(), \"bin\", \".bin-manifest.json\");\n}\n\nfunction sha256File(path: string): string | null {\n  try {\n    return createHash(\"sha256\").update(readFileSync(path)).digest(\"hex\");\n  } catch {\n    return null;\n  }","sourceCodeStart":2202,"sourceCodeEnd":2238,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L2202-L2238","documentation":"setupPlatform maps the current OS/architecture to release binaries and only supports darwin/linux/win32 on arm64/amd64 (x64 is normalized to amd64). Anything else — e.g. freebsd, alpine-mips, or 32-bit x86 — throws the OFF_STATES.unsupportedPlatform message.","triggerScenarios":"Running setup on an unsupported platform: linux with arch 'arm'/'ia32', win32 on arm (pre-nodeArch arm64 handling), FreeBSD/OpenBSD, or process.arch values like 'ppc64' or 's390x'.","commonSituations":"Running in unusual CI containers (linux/386), on Raspberry Pi 32-bit OS, or inside emulation where Node reports a non-standard arch.","solutions":["Run on a supported platform: darwin/linux/win32 with arm64 or amd64 hardware.","Use a 64-bit OS image (x64/arm64) instead of a 32-bit one.","Build/install the binaries manually from source if your platform is not in the release matrix."],"exampleFix":"// before (32-bit container)\n$ cave setup\nError: unsupported platform linux/ia32\n\n// after\n# use a 64-bit image\ndocker run --platform linux/amd64 -it ... cave setup","handlingStrategy":"fallback","validationCode":"const okOs = ['darwin', 'linux', 'win32'].includes(process.platform);\nconst arch = process.arch === 'x64' ? 'amd64' : process.arch;\nconst okArch = ['arm64', 'amd64'].includes(arch);\nif (!okOs || !okArch) console.warn(`unsupported platform ${process.platform}/${arch}; use darwin/linux/win32 on arm64/amd64`);","typeGuard":"const isSupportedPlatform = (os: NodeJS.Platform, arch: string): boolean =>\n  ['darwin', 'linux', 'win32'].includes(os) && ['arm64', 'amd64'].includes(arch === 'x64' ? 'amd64' : arch);","tryCatchPattern":"try {\n  setupPlatform();\n} catch (error) {\n  console.error(`${error.message}\\nBuild binaries from source or run on a supported platform.`);\n  process.exit(1);\n}","preventionTips":["Pin CI runners to linux/amd64 or linux/arm64 images","Avoid 32-bit and exotic-arch (ppc64le, s390x) environments for setup","Document the supported platform matrix in your project README"],"tags":["platform","compatibility"],"backgroundTag":"unsupported-platform","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}