{"record":{"id":"8a609a9f1635b0b8","repo":"pydantic/monty","slug":"could-not-locate-the-monty-binary-tried-tried-join-install","errorCode":null,"errorMessage":"could not locate the monty binary (tried: ${tried.join(', ')}). Install the platform package, set MONTY_BIN, or pass binaryPath.","messagePattern":"could not locate the monty binary \\(tried: (.+?)\\)\\. Install the platform package, set MONTY_BIN, or pass binaryPath\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"crates/monty-js/ts/binary.ts","lineNumber":76,"sourceCode":"  const fromPackage = platformPackageBinary()\n  if (fromPackage !== null) {\n    return fromPackage\n  }\n  tried.push('platform package @pydantic/monty-<platform>')\n\n  const fromPath = searchPath()\n  if (fromPath !== null) {\n    return fromPath\n  }\n  tried.push('PATH')\n\n  const fromWorkspace = workspaceBinary()\n  if (fromWorkspace !== null) {\n    return fromWorkspace\n  }\n  tried.push('cargo workspace target/')\n\n  throw new Error(\n    `could not locate the monty binary (tried: ${tried.join(', ')}). ` +\n      'Install the platform package, set MONTY_BIN, or pass binaryPath.',\n  )\n}\n\n/**\n * The binary shipped by the platform-specific npm package, if installed.\n *\n * Resolution failures fall through to the next strategy rather than erroring:\n * the same package names previously shipped napi `.node` bindings, so a stale\n * install can resolve while holding no `monty` executable.\n */\nfunction platformPackageBinary(): string | null {\n  const triple = platformTriple()\n  if (triple === null) {\n    return null\n  }\n  const require = createRequire(import.meta.url)","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/pydantic/monty/blob/adc986b362e3961f407868cb118a99fe831b9e61/crates/monty-js/ts/binary.ts#L58-L94","documentation":"Thrown by `findMontyBinary` after exhausting every automatic resolution strategy — `MONTY_BIN`, the `@pydantic/monty-<platform>` optional package, `PATH`, and the cargo workspace `target/` build — without finding an executable `monty` binary. The message lists each location tried so you can see exactly what was skipped. Worker subprocesses cannot start without the binary, so this fails before any code runs.","triggerScenarios":"Creating a `Monty` pool when: the platform package `@pydantic/monty-<platform>` was not installed (e.g. npm installed with `--omit=optional`, or an unsupported platform/arch triple like linux-musl or win32-arm64 where `platformTriple()` returns null); `MONTY_BIN` is unset or points at a missing file; `monty` is not on PATH; and the process does not run inside a cargo workspace with a built binary.","commonSituations":"CI caches node_modules without optional dependencies; deploying to an unsupported platform (Alpine/musl, ARM Windows); Docker multi-stage builds that drop the runtime binary; users who installed `@pydantic/monty-client` alone expecting it to contain the worker binary.","solutions":["Install the platform package: `npm i @pydantic/monty-linux-x64-gnu` (match your `platformTriple()`), or reinstall without `--omit=optional`","Set `MONTY_BIN` to an absolute path of an existing `monty` executable","Pass `binaryPath` explicitly when creating the pool","In development, build from source: `cargo build -p monty-runtime` inside the workspace so `target/debug/monty` exists","Check the `tried:` list in the message to see which strategies were skipped and why"],"exampleFix":"// before\nconst pool = await Monty.create() // fails when optional deps were omitted\n// after\n// .npmrc: omit=[]  (do not exclude optional deps)\n// or, in CI:\nconst pool = await Monty.create({ binaryPath: '/usr/local/bin/monty' })","handlingStrategy":"validation","validationCode":"import { findMontyBinary } from '@pydantic/monty'\n// fail fast at startup with your own message\nlet bin: string\ntry { bin = findMontyBinary() } catch { bin = '' }\nif (!bin) throw new Error('monty worker binary unavailable: install the platform package or set MONTY_BIN')","typeGuard":"const binaryAvailable = (): boolean => {\n  try { findMontyBinary(); return true } catch { return false }\n}","tryCatchPattern":"try {\n  pool = await Monty.create()\n} catch (err) {\n  if ((err as Error).message.includes('could not locate the monty binary')) {\n    // surface install guidance to the operator\n    throw new Error('run: npm i @pydantic/monty-' + process.platform + '-x64-gnu, or set MONTY_BIN')\n  }\n  throw err\n}","preventionTips":["Ensure optional dependencies are installed (no `--omit=optional` in npm ci)","Pin the correct platform package for your target triple in Docker/CI images","Set `MONTY_BIN` as an explicit escape hatch in deployment environments","Call `findMontyBinary()` early at boot to fail fast with a clear message"],"tags":["nodejs","missing-dependency","installation"],"backgroundTag":"missing-dependency","analyzedSha":"adc986b362e3961f407868cb118a99fe831b9e61","analyzedAt":"2026-09-13T19:19:18.698Z","contentChangedAt":"2026-09-13T19:19:18.698Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}