pydantic/monty · critical · Error

could not locate the monty binary

Error message

could not locate the monty binary (tried: ${tried.join(', ')}). Install the platform package, set MONTY_BIN, or pass binaryPath.

What it means

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.

Solutions

1. Install the platform package: `npm i @pydantic/monty-linux-x64-gnu` (match your `platformTriple()`), or reinstall without `--omit=optional`
2. Set `MONTY_BIN` to an absolute path of an existing `monty` executable
3. Pass `binaryPath` explicitly when creating the pool
4. In development, build from source: `cargo build -p monty-runtime` inside the workspace so `target/debug/monty` exists
5. Check the `tried:` list in the message to see which strategies were skipped and why

Example fix

// before
const pool = await Monty.create() // fails when optional deps were omitted
// after
// .npmrc: omit=[]  (do not exclude optional deps)
// or, in CI:
const pool = await Monty.create({ binaryPath: '/usr/local/bin/monty' })

import { findMontyBinary } from '@pydantic/monty'
// fail fast at startup with your own message
let bin: string
try { bin = findMontyBinary() } catch { bin = '' }
if (!bin) throw new Error('monty worker binary unavailable: install the platform package or set MONTY_BIN')

const binaryAvailable = (): boolean => {
  try { findMontyBinary(); return true } catch { return false }
}

try {
  pool = await Monty.create()
} catch (err) {
  if ((err as Error).message.includes('could not locate the monty binary')) {
    // surface install guidance to the operator
    throw new Error('run: npm i @pydantic/monty-' + process.platform + '-x64-gnu, or set MONTY_BIN')
  }
  throw err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• monty binary not found at binaryPath

AI-assisted analysis of pydantic/monty@adc986b362 (2026-09-13). Data as JSON: /api/errors/8a609a9f1635b0b8. Report an issue: GitHub.

Appendix: source

Thrown at crates/monty-js/ts/binary.ts:76

  const fromPackage = platformPackageBinary()
  if (fromPackage !== null) {
    return fromPackage
  }
  tried.push('platform package @pydantic/monty-<platform>')

  const fromPath = searchPath()
  if (fromPath !== null) {
    return fromPath
  }
  tried.push('PATH')

  const fromWorkspace = workspaceBinary()
  if (fromWorkspace !== null) {
    return fromWorkspace
  }
  tried.push('cargo workspace target/')

  throw new Error(
    `could not locate the monty binary (tried: ${tried.join(', ')}). ` +
      'Install the platform package, set MONTY_BIN, or pass binaryPath.',
  )
}

/**
 * The binary shipped by the platform-specific npm package, if installed.
 *
 * Resolution failures fall through to the next strategy rather than erroring:
 * the same package names previously shipped napi `.node` bindings, so a stale
 * install can resolve while holding no `monty` executable.
 */
function platformPackageBinary(): string | null {
  const triple = platformTriple()
  if (triple === null) {
    return null
  }
  const require = createRequire(import.meta.url)

View on GitHub (pinned to adc986b362)