emotion-js/emotion · error · Error

The 'autoLabel' option must be undefined, or one of the…

Error message

The 'autoLabel' option must be undefined, or one of the following: ${AUTO_LABEL_VALUES.map(
        s => `"${s}"`
      ).join(', ')}

What it means

The `autoLabel` option of @emotion/babel-plugin only accepts specific string values (dev, production, always). The plugin validates the option at setup and throws if it's set to anything else, preventing silently wrong label behavior.

Solutions

Change `autoLabel` to one of the allowed values: "dev", "production", or "always"
Remove the `autoLabel` option entirely to use the default (dev)
Check spelling/quotes: the value must be a string, not a boolean

Example fix

// before
['@emotion/babel-plugin', { autoLabel: true }]
// after
['@emotion/babel-plugin', { autoLabel: 'dev' }]

Defensive patterns

Strategy: validation

Validate before calling

const AUTO_LABEL_VALUES = ['dev', 'production', 'always'];
if (opts.autoLabel !== undefined && !AUTO_LABEL_VALUES.includes(opts.autoLabel)) {
  throw new Error(`autoLabel must be one of: ${AUTO_LABEL_VALUES.map(v => `"${v}"`).join(', ')}`);
}

Type guard

const isAutoLabel = (v) => v === undefined || ['dev', 'production', 'always'].includes(v);

Prevention

Never pass booleans to autoLabel — it's a string enum
Type the babel options with a union type: type AutoLabel = 'dev' | 'production' | 'always'
Omit the option to accept the default

When it happens

Trigger: Setting `autoLabel` to an unsupported value like true, false, 'true', or a misspelling such as 'produciton' in the babel plugin options.

Common situations: Treating autoLabel as a boolean toggle instead of an enum, typos after hand-editing babel config, or copying configs from outdated blog posts.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of emotion-js/emotion@b882bcba85 (2026-09-02). Data as JSON: /api/errors/c5da62a7fdc1039f. Report an issue: GitHub.

Appendix: source

Thrown at packages/babel-plugin/src/index.js:83

  primitivesStyled: primitivesStyledMacro,
  webStyled: webStyledMacro,
  vanillaEmotion: vanillaEmotionMacro
}

/*
export type BabelPath = any

export type EmotionBabelPluginPass = any
*/

const AUTO_LABEL_VALUES = ['dev-only', 'never', 'always']

export default function (babel, options) {
  if (
    options.autoLabel !== undefined &&
    !AUTO_LABEL_VALUES.includes(options.autoLabel)
  ) {
    throw new Error(
      `The 'autoLabel' option must be undefined, or one of the following: ${AUTO_LABEL_VALUES.map(
        s => `"${s}"`
      ).join(', ')}`
    )
  }

  let t = babel.types
  return {
    name: '@emotion',
    // https://github.com/babel/babel/blob/0c97749e0fe8ad845b902e0b23a24b308b0bf05d/packages/babel-plugin-syntax-jsx/src/index.ts#L9-L18
    manipulateOptions(opts, parserOpts) {
      const { plugins } = parserOpts

      if (
        plugins.some(p => {
          const plugin = Array.isArray(p) ? p[0] : p
          return plugin === 'typescript' || plugin === 'jsx'
        })

View on GitHub (pinned to b882bcba85)