gatsbyjs/gatsby · error

keepDynamicImports option needs to be set

Error message

keepDynamicImports option needs to be set

What it means

Thrown by `babel-transform-mark-to-keep-dynamic-import` (babel-transform-mark-to-keep-dynamic-import.js:28) at plugin setup when `opts.keepDynamicImports` is falsy. The plugin's job is to mark certain dynamic `import()` calls so they survive babel transformation; without the list of paths to keep, it has nothing to do and refuses to run.

Source

Thrown at packages/babel-preset-gatsby-package/lib/babel-transform-mark-to-keep-dynamic-import.js:28

 */

/**
 * @typedef {Object} IPluginOptions
 * @property {Array<string>} keepDynamicImports
 */

/**
 *
 * @param {{ types: BabelTypes }} _unused
 * @param {Partial<IPluginOptions>} opts
 * @returns {PluginObj}
 */
module.exports = function keepDynamicImports(
  _unused,
  opts
) {
  if (!opts.keepDynamicImports) {
    throw new Error(`keepDynamicImports option needs to be set`)
  } else if (!Array.isArray(opts.keepDynamicImports)) {
    throw new Error(`keepDynamicImports option needs to be an array`)
  }

  const absolutePaths = opts.keepDynamicImports.map(p => path.resolve(p))

  return {
    name: `babel-transform-mark-to-keep-dynamic-import`,
    visitor: {
      Program() {
        const filename = this.file?.opts?.filename
        if (!filename) {
          return
        }

        if (absolutePaths.includes(filename)) {
          // this is big hack - it relies on some babel plugins internal to basically
          // do early return ( https://github.com/babel/babel/blob/3526b79c87863052f1c61ec0c49c0fc287ba32e6/packages/babel-plugin-transform-modules-commonjs/src/index.ts#L174 )

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass `keepDynamicImports` as an array of module paths: `{ keepDynamicImports: ['gatsby-plugin-theme-ui'] }`.
2. If you do not need to preserve any dynamic imports, remove the plugin entirely.
3. Ensure the preset forwards `keepDynamicImports` down to the plugin.

Example fix

// before
keepDynamicImports(_unused, {})

// after
keepDynamicImports(_unused, { keepDynamicImports: ['gatsby-plugin-theme-ui'] })

function pluginHasKeepDynamicImportsOption(opts) {
  return Boolean(opts && opts.keepDynamicImports)
}

/** @returns {opts is { keepDynamicImports: unknown[] }} */
function hasKeepDynamicImportsArray(opts) {
  return opts != null && Array.isArray(opts.keepDynamicImports)
}

When it happens

Trigger: Registering the plugin without `keepDynamicImports`; passing `{ keepDynamicImports: null }`; the preset not forwarding this option to the plugin.

Common situations: Configuring babel-preset-gatsby-package manually and omitting the option; integrating the plugin standalone; refactoring the preset and losing the option plumbing.

Related errors

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

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