babel/babel · error · ReferenceError

BABEL_HELPER_UNKNOWN

BABEL_HELPER_UNKNOWN

Error message

Unknown helper ${name}

What it means

Thrown by @babel/helpers' internal loadHelper() when a requested helper name is absent from the build-time-generated helpers registry (helpers-generated.ts). The package only ships a fixed set of helper ASTs; the public get(), minVersion(), and getDependencies() functions all route through loadHelper(), so any unlisted name aborts with a ReferenceError carrying code BABEL_HELPER_UNKNOWN and a `helper` field. It is a hard failure because the transform pipeline cannot synthesize a helper it does not know about.

Source

Thrown at packages/babel-helpers/src/index.ts:99

  build: (
    getDependency: GetDependency | undefined,
    bindingName: string | undefined,
    localBindings: string[] | undefined,
    adjustAst: AdjustAst | undefined,
  ) => {
    nodes: t.Program["body"];
    globals: string[];
  };
  minVersion: string;
  getDependencies: () => string[];
}

const helperData: Record<string, HelperData> = Object.create(null);
function loadHelper(name: string) {
  if (!helperData[name]) {
    const helper = helpers[name];
    if (!helper) {
      throw Object.assign(new ReferenceError(`Unknown helper ${name}`), {
        code: "BABEL_HELPER_UNKNOWN",
        helper: name,
      });
    }

    helperData[name] = {
      minVersion: helper.minVersion,
      build(getDependency, bindingName, localBindings, adjustAst) {
        const ast = helper.ast();
        permuteHelperAST(
          ast,
          helper.metadata,
          bindingName,
          localBindings,
          getDependency,
          adjustAst,
        );

View on GitHub (pinned to 06b6eae39d)

Solutions

1. Print helpers.list (exported from @babel/helpers) and confirm the requested name is present; correct the call to use an existing helper name.
2. Align all @babel/* packages to the same major/minor version (e.g. force a single @babel/helpers version in the lockfile) so the plugin and helpers agree on which names exist.
3. Clear caches and reinstall: remove node_modules and the package lock, then reinstall, to drop any stale helpers-generated artifacts.
4. Update or patch the offending plugin to use the current helper name; if it is your own plugin, run its tests against the installed @babel/helpers.
5. If you need a helper not in the registry, inject the runtime code yourself via file.addImport / a custom template instead of file.addHelper.

Example fix

// before
import helpers from "@babel/helpers";
const { nodes } = helpers.get("interopRequireWilde"); // typo, throws BABEL_HELPER_UNKNOWN

// after
import helpers, { list } from "@babel/helpers";
const name = "interopRequireWildcard";
if (!list.includes(name)) {
  throw new Error(`helper ${name} is not available in @babel/helpers ${helpers.minVersion.bind(null, name)}`);
}
const { nodes } = helpers.get(name);

import helpers, { list } from "@babel/helpers";

// `list` is the canonical set of public helper names (leading _ stripped).
// Call this before helpers.get / helpers.minVersion / helpers.getDependencies.
export function assertHelperExists(name: string): void {
  if (!list.includes(name)) {
    throw new Error(
      `Unknown Babel helper "${name}". Known helpers: ${list.join(", ")}`,
    );
  }
}

// Usage:
// assertHelperExists(requestedName);
// helpers.get(requestedName, getDependency);

import { list } from "@babel/helpers";

const HELPER_NAMES = new Set(list);

export function isKnownHelper(name: string): name is (typeof list)[number] {
  return HELPER_NAMES.has(name);
}

// Usage with narrowing:
// if (isKnownHelper(name)) { helpers.get(name); /* name narrowed */ }

try {
  const { nodes } = helpers.get(name);
  // ...
} catch (err) {
  if (err?.code === "BABEL_HELPER_UNKNOWN") {
    // err.helper holds the bad name; fall back to inlining the runtime code
    // or skip the transform for this node.
    throw new Error(
      `This build of @babel/helpers does not provide helper "${err.helper}". ` +
        `Align @babel/* versions or inline the runtime manually.`,
    );
  }
  throw err; // rethrow unrelated errors
}

When it happens

Trigger: Calling helpers.get("fooBar") (or helpers.minVersion / helpers.getDependencies) with a name that is not in the generated registry; a Babel plugin invoking file.addHelper() with a typo'd or stale name; version skew where a plugin compiled against a newer @babel/helpers requests a helper that the installed older version does not define; referencing a renamed helper (e.g. one prefixed or restructured between major versions).

Common situations: Mismatched @babel/core and @babel/helpers versions in a lockfile (helpers added/renamed across releases); a custom or third-party plugin hardcoding a helper name that was removed; stale node_modules after a partial upgrade leaving an outdated helpers-generated.ts; monorepo hoisting resolving a different @babel/helpers copy than the plugin was authored against; typos in hand-written plugin code calling file.addHelper("interopRequireWilde").

Related errors

• Cannot use internal helper ${name}
• attempted to use private field on non-instance
• Invalid attempt to iterate non-iterable instance. In order t
• Invalid attempt to iterate non-iterable instance. In order t
• Super expression must either be null or a function

AI-assisted analysis of babel/babel@06b6eae39d (2026-08-03). Data as JSON: /data/errors/45b61f09f5a24221.json. Report an issue: GitHub.