gatsbyjs/gatsby · error

availableFlags option needs to be set

Error message

availableFlags option needs to be set

What it means

Thrown by `babel-transform-compiler-flags` (babel-transform-compiler-flags.js:33) when `opts.availableFlags` is falsy. The plugin uses `availableFlags` as the whitelist of allowed `_CFLAGS_.<name>` accesses; without it, any unknown flag would silently resolve to empty string, so it fails fast at setup.

Source

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

 */

/**
 *
 * @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
        const availableFlags = /** @type {IPluginOptions} */ (state.opts).availableFlags

        if (

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass `availableFlags` as an array of allowed flag names: `{ availableFlags: ['PRESERVE_FILE_DOWNLOADS', '...'] }`.
2. Keep `availableFlags` in sync with the keys that appear in source as `_CFLAGS_.*`.
3. Generate `availableFlags` from the same source the flags map is derived from.

Example fix

// before
compilerFlags({ types: t }, { flags: { A: '1' } })

// after
compilerFlags({ types: t }, {
  flags: { A: '1' },
  availableFlags: ['A'],
})

function pluginHasAvailableFlagsOption(opts) {
  return Boolean(opts && Array.isArray(opts.availableFlags))
}

/** @returns {opts is { availableFlags: string[] }} */
function hasAvailableFlags(opts) {
  return opts != null && Array.isArray(opts.availableFlags)
}

When it happens

Trigger: Passing `{ flags: {...} }` without `availableFlags`; passing a null/undefined `availableFlags`; miswiring the preset so only `flags` is forwarded.

Common situations: Configuring the plugin manually and missing the whitelist; refactoring the preset and dropping the availableFlags plumbing.

Related errors

• flags 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/cf1bae77a0159ed9. Report an issue: GitHub.