What causes "Can't find 'elm' binary." in parcel-bundler/parcel?

Add elm as a dev dependency: `npm install -D elm` or `yarn add -D elm` (preferred — reproducible across machines).

parcel-bundler/parcel · error · ThrowableDiagnostic

Can't find 'elm' binary.

Error message

Can't find 'elm' binary.

What it means

Thrown by elmBinaryPath() when neither a local `elm` package (resolved via require.resolve('elm/package.json')) nor a global `elm` on PATH is found. The check runs both when elm.json is missing (to give a combined hint) and when the binary is actually needed for compilation. Diagnostic lists install instructions.

Source

Thrown at packages/transformers/elm/src/loadConfig.js:32

      diagnostic: {
        origin: '@parcel/elm-transformer',
        message: "The 'elm.json' file is missing.",
        hints: [
          "Initialize your elm project by running 'elm init'",
          "If you installed elm as project dependency then run 'yarn elm init' or 'npx elm init'",
        ],
      },
    });
  }

  return null;
}

function elmBinaryPath(): ?string {
  let elmBinary = resolveLocalElmBinary();

  if (elmBinary == null && !commandExists.sync('elm')) {
    throw new ThrowableDiagnostic({
      diagnostic: {
        message: "Can't find 'elm' binary.",
        hints: [
          "You can add it as an dependency for your project by running 'yarn add -D elm' or 'npm add -D elm'",
          'If you want to install it globally then follow instructions on https://elm-lang.org/',
        ],
        origin: '@parcel/elm-transformer',
      },
    });
  }

  return elmBinary;
}

function resolveLocalElmBinary() {
  try {
    let result = require.resolve('elm/package.json');
    // $FlowFixMe

View on GitHub (pinned to 59484858a1)

Solutions

Add elm as a dev dependency: `npm install -D elm` or `yarn add -D elm` (preferred — reproducible across machines).
If you prefer global install, ensure `elm` is on PATH in the build environment (`which elm` from the same shell).
Re-run `npm ci` / `yarn install --force` if the elm package was partially installed.
For pnpm, ensure elm is resolvable from the workspace that owns the Elm files.

Example fix

# before: only global elm, missing in CI
# after
npm install -D elm

Defensive patterns

Strategy: validation

Validate before calling

const commandExists = require('command-exists');
function assertElmAvailable() {
  try { require.resolve('elm/package.json'); return; } catch {}
  if (!commandExists.sync('elm')) {
    throw new Error('elm binary missing — run `npm i -D elm`');
  }
}

Prevention

Always install elm as a dev dependency rather than relying on a global install.
Pin the elm version in package.json so CI matches local.

When it happens

Trigger: Any Elm transform that needs to invoke the compiler: resolveLocalElmBinary() returns null (no local `elm` npm package) AND commandExists.sync('elm') returns false.

Common situations: Fresh clone of an Elm project whose elm dependency was not installed (`npm ci` skipped optional deps); CI image without global elm and no local dependency; switching node_modules between yarn/pnpm where `elm` is not hoisted; the user only installed elm globally but PATH in the build env differs.

Related errors

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/dfecc947ee5c7935. Report an issue: GitHub.