babel/babel · error · Error

The decorators plugin requires a 'version' option, whose val

Error message

The decorators plugin requires a 'version' option, whose value must be one of: '2023-11' or 'legacy'.

What it means

Thrown by @babel/plugin-syntax-decorators (index.ts:13) when no `version` option is provided. Because decorators have two mutually incompatible spec drafts (the 2023-11 stage-3 spec and the legacy TC39 stage-1 spec), the parser cannot pick one implicitly — Babel 7.21+ made `version` mandatory to disambiguate parser behavior.

Source

Thrown at packages/babel-plugin-syntax-decorators/src/index.ts:13

import { declare } from "@babel/helper-plugin-utils";

export interface Options {
  version?: "legacy" | "2023-11";
}

export default declare((api, options: Options) => {
  api.assertVersion(REQUIRED_VERSION("^7.0.0-0 || ^8.0.0"));

  const { version } = options;

  if (version === undefined) {
    throw new Error(
      "The decorators plugin requires a 'version' option, whose value must be one of: " +
        "'2023-11' or 'legacy'.",
    );
  }
  if (version !== "2023-11" && version !== "legacy") {
    throw new Error(
      "Unsupported decorators version: " + JSON.stringify(version),
    );
  }
  if ("legacy" in options) {
    throw new Error(
      `The .legacy option has been removed in Babel 8. Use .version: "legacy" instead.`,
    );
  }
  if ("decoratorsBeforeExport" in options) {
    throw new Error(
      `The .decoratorsBeforeExport option has been removed in Babel 8. The decorators can come either before or after exports.`,
    );

View on GitHub (pinned to 06b6eae39d)

Solutions

1. Add `{ version: "2023-11" }` for the current spec (recommended for new code), OR `{ version: "legacy" }` for TS/Aurelia/legacy Babel behavior.
2. Place the decorators plugin before @babel/plugin-transform-class-properties / transform-class-features in the plugins array (ordering matters for legacy mode).

Example fix

// before
plugins: ["@babel/plugin-proposal-decorators"]
// after
plugins: [["@babel/plugin-proposal-decorators", { version: "2023-11" }]]

const dec = config.plugins.find(p => Array.isArray(p) && /decorators$/.test(p[0]));
const opts = (dec && dec[1]) || {};
if (opts.version !== "2023-11" && opts.version !== "legacy") {
  throw new Error("decorators plugin needs version: '2023-11' or 'legacy'");
}

function isValidDecoratorsVersion(v: unknown): v is "2023-11" | "legacy" {
  return v === "2023-11" || v === "legacy";
}

When it happens

Trigger: Loading the decorators plugin as a bare string `"@babel/plugin-proposal-decorators"` or `"@babel/plugin-syntax-decorators"`, or as `["...", {}]` with no `version` key. The check is `if (version === undefined)` at index.ts:12.

Common situations: Upgrading from Babel <7.21 where decorators defaulted to legacy, or copying a tutorial that predates the mandatory-version requirement. Also common when migrating TypeScript decorator configs to Babel without specifying the version.

Related errors

• Decorating class property failed. Please ensure that transfo
• Unsupported decorators version: ${version}
• The partial application plugin requires a "version" option.
• The pipeline plugin requires a "proposal" option. "proposal"
• More than one plugin attempted to override parsing.

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