{"id":"45b61f09f5a24221","repo":"babel/babel","slug":"babel-helper-unknown","errorCode":"BABEL_HELPER_UNKNOWN","errorMessage":"Unknown helper ${name}","messagePattern":"Unknown helper (.+?)","errorType":"error_code","errorClass":"ReferenceError","httpStatus":null,"severity":"error","filePath":"packages/babel-helpers/src/index.ts","lineNumber":99,"sourceCode":"  build: (\n    getDependency: GetDependency | undefined,\n    bindingName: string | undefined,\n    localBindings: string[] | undefined,\n    adjustAst: AdjustAst | undefined,\n  ) => {\n    nodes: t.Program[\"body\"];\n    globals: string[];\n  };\n  minVersion: string;\n  getDependencies: () => string[];\n}\n\nconst helperData: Record<string, HelperData> = Object.create(null);\nfunction loadHelper(name: string) {\n  if (!helperData[name]) {\n    const helper = helpers[name];\n    if (!helper) {\n      throw Object.assign(new ReferenceError(`Unknown helper ${name}`), {\n        code: \"BABEL_HELPER_UNKNOWN\",\n        helper: name,\n      });\n    }\n\n    helperData[name] = {\n      minVersion: helper.minVersion,\n      build(getDependency, bindingName, localBindings, adjustAst) {\n        const ast = helper.ast();\n        permuteHelperAST(\n          ast,\n          helper.metadata,\n          bindingName,\n          localBindings,\n          getDependency,\n          adjustAst,\n        );\n","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/babel/babel/blob/06b6eae39da4ce0689fad64e2c48a6375a464208/packages/babel-helpers/src/index.ts#L81-L117","documentation":"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.","triggerScenarios":"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).","commonSituations":"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\").","solutions":["Print helpers.list (exported from @babel/helpers) and confirm the requested name is present; correct the call to use an existing helper name.","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.","Clear caches and reinstall: remove node_modules and the package lock, then reinstall, to drop any stale helpers-generated artifacts.","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.","If you need a helper not in the registry, inject the runtime code yourself via file.addImport / a custom template instead of file.addHelper."],"exampleFix":"// before\nimport helpers from \"@babel/helpers\";\nconst { nodes } = helpers.get(\"interopRequireWilde\"); // typo, throws BABEL_HELPER_UNKNOWN\n\n// after\nimport helpers, { list } from \"@babel/helpers\";\nconst name = \"interopRequireWildcard\";\nif (!list.includes(name)) {\n  throw new Error(`helper ${name} is not available in @babel/helpers ${helpers.minVersion.bind(null, name)}`);\n}\nconst { nodes } = helpers.get(name);","handlingStrategy":"validation","validationCode":"import helpers, { list } from \"@babel/helpers\";\n\n// `list` is the canonical set of public helper names (leading _ stripped).\n// Call this before helpers.get / helpers.minVersion / helpers.getDependencies.\nexport function assertHelperExists(name: string): void {\n  if (!list.includes(name)) {\n    throw new Error(\n      `Unknown Babel helper \"${name}\". Known helpers: ${list.join(\", \")}`,\n    );\n  }\n}\n\n// Usage:\n// assertHelperExists(requestedName);\n// helpers.get(requestedName, getDependency);","typeGuard":"import { list } from \"@babel/helpers\";\n\nconst HELPER_NAMES = new Set(list);\n\nexport function isKnownHelper(name: string): name is (typeof list)[number] {\n  return HELPER_NAMES.has(name);\n}\n\n// Usage with narrowing:\n// if (isKnownHelper(name)) { helpers.get(name); /* name narrowed */ }","tryCatchPattern":"try {\n  const { nodes } = helpers.get(name);\n  // ...\n} catch (err) {\n  if (err?.code === \"BABEL_HELPER_UNKNOWN\") {\n    // err.helper holds the bad name; fall back to inlining the runtime code\n    // or skip the transform for this node.\n    throw new Error(\n      `This build of @babel/helpers does not provide helper \"${err.helper}\". ` +\n        `Align @babel/* versions or inline the runtime manually.`,\n    );\n  }\n  throw err; // rethrow unrelated errors\n}","preventionTips":["Pin every @babel/* package to one version range in package.json so a plugin never asks for a helper the installed @babel/helpers lacks.","When authoring a plugin, gate helper usage on file.availableHelper(name, version) before calling file.addHelper(name) — transform-runtime itself does this at index.ts:121.","Treat helper names as an enumerated API: import { list } from \"@babel/helpers\" and validate dynamically if names come from config or user input.","After upgrading @babel packages, search your codebase for file.addHelper / helpers.get calls and reconcile them against the new list export.","In CI, assert that `npm ls @babel/helpers` resolves to a single version to catch hoisting-induced version skew early."],"tags":["babel","helpers","plugin","version-mismatch","registry"],"analyzedSha":"06b6eae39da4ce0689fad64e2c48a6375a464208","analyzedAt":"2026-08-03T20:13:43.465Z","schemaVersion":2}