{"record":{"id":"9b87b6a68c710976","repo":"gatsbyjs/gatsby","slug":"flags-option-needs-to-be-set","errorCode":null,"errorMessage":"flags option needs to be set","messagePattern":"flags option needs to be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/babel-preset-gatsby-package/lib/babel-transform-compiler-flags.js","lineNumber":30,"sourceCode":" * @typedef {Object} IPluginOptions\n * @property {Record<string, string>} flags\n * @property {Array<string>} availableFlags\n */\n\n/**\n *\n * @param {{ types: BabelTypes }} args\n * @param {Partial<IPluginOptions>} opts\n * @returns {PluginObj}\n */\nmodule.exports = function compilerFlags(\n  {\n    types: t,\n  },\n  opts\n) {\n  if (!opts.flags) {\n    throw new Error(`flags option needs to be set`)\n  }\n  if (!opts.availableFlags) {\n    throw new Error(`availableFlags option needs to be set`)\n  }\n\n  return {\n    name: `babel-transform-compiler-flags`,\n    visitor: {\n      /**\n       * @param {NodePath} nodePath\n       * @param {PluginPass} state\n       */\n      Identifier(\n        nodePath,\n        state\n      ) {\n        const identifier = /** @type {Identifier} */ (nodePath.node)\n        const flags = /** @type {IPluginOptions} */ (state.opts).flags","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/babel-preset-gatsby-package/lib/babel-transform-compiler-flags.js#L12-L48","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass `flags` as a string-keyed object: `{ flags: { PRESERVE_FILE_DOWNLOADS: 'true', ... } }`.","If using via the preset, ensure the preset forwards flags to the plugin.","Check that the option is not being overridden by a spread that nulls it."],"exampleFix":"// before\nrequire('babel-transform-compiler-flags')({ types: t }, {})\n\n// after\nrequire('babel-transform-compiler-flags')({ types: t }, {\n  flags: { PRESERVE_FILE_DOWNLOADS: 'true' },\n  availableFlags: ['PRESERVE_FILE_DOWNLOADS'],\n})","handlingStrategy":"validation","validationCode":"function pluginHasFlagsOption(opts) {\n  return Boolean(opts && opts.flags) && typeof opts.flags === 'object'\n}","typeGuard":"/** @returns {opts is { flags: Record<string,string> }} */\nfunction hasFlags(opts) {\n  return opts != null && typeof opts.flags === 'object' && opts.flags !== null\n}","tryCatchPattern":null,"preventionTips":["Always pass both flags and availableFlags to the plugin/preset.","Centralize flag configuration so it cannot be partially omitted.","Document required options wherever the plugin is registered."],"tags":["babel","config","flags","compiler"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}