gatsbyjs/gatsby · error

flags option needs to be set

Error message

flags option needs to be set

What it means

Thrown by the `babel-transform-compiler-flags` plugin (babel-transform-compiler-flags.js:30) at plugin instantiation when `opts.flags` is falsy. The plugin replaces `_CFLAGS_.<name>` references with literal values at build time; it cannot operate without the flags map, so it hard-fails during babel setup rather than silently producing empty replacements.

Source

Thrown at packages/babel-preset-gatsby-package/lib/babel-transform-compiler-flags.js:30

 * @typedef {Object} IPluginOptions
 * @property {Record<string, string>} flags
 * @property {Array<string>} availableFlags
 */

/**
 *
 * @param {{ types: BabelTypes }} args
 * @param {Partial<IPluginOptions>} opts
 * @returns {PluginObj}
 */
module.exports = function compilerFlags(
  {
    types: t,
  },
  opts
) {
  if (!opts.flags) {
    throw new Error(`flags option needs to be set`)
  }
  if (!opts.availableFlags) {
    throw new Error(`availableFlags option needs to be set`)
  }

  return {
    name: `babel-transform-compiler-flags`,
    visitor: {
      /**
       * @param {NodePath} nodePath
       * @param {PluginPass} state
       */
      Identifier(
        nodePath,
        state
      ) {
        const identifier = /** @type {Identifier} */ (nodePath.node)
        const flags = /** @type {IPluginOptions} */ (state.opts).flags

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass `flags` as a string-keyed object: `{ flags: { PRESERVE_FILE_DOWNLOADS: 'true', ... } }`.
2. If using via the preset, ensure the preset forwards flags to the plugin.
3. Check that the option is not being overridden by a spread that nulls it.

Example fix

// before
require('babel-transform-compiler-flags')({ types: t }, {})

// after
require('babel-transform-compiler-flags')({ types: t }, {
  flags: { PRESERVE_FILE_DOWNLOADS: 'true' },
  availableFlags: ['PRESERVE_FILE_DOWNLOADS'],
})

function pluginHasFlagsOption(opts) {
  return Boolean(opts && opts.flags) && typeof opts.flags === 'object'
}

/** @returns {opts is { flags: Record<string,string> }} */
function hasFlags(opts) {
  return opts != null && typeof opts.flags === 'object' && opts.flags !== null
}

When it happens

Trigger: Registering the plugin without passing the `flags` option; passing `{ flags: null }` or `{ flags: undefined }`; misconfiguring the preset that wraps this plugin so options are not forwarded.

Common situations: Customizing babel-preset-gatsby-package and omitting the flags option; upgrading the preset where the option name changed; integrating the plugin standalone and forgetting required options.

Related errors

• availableFlags option needs to be set
• ${cFlag} is not part of the available compiler flags.
• keepDynamicImports option needs to be set
• BabelPluginRemoveGraphQLQueries: the "${exportName}" export
• keepDynamicImports option needs to be an array

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/9b87b6a68c710976. Report an issue: GitHub.