gatsbyjs/gatsby · error

Support for custom Promise polyfills has been removed in Gat

Error message

Support for custom Promise polyfills has been removed in Gatsby v2. We only support Babel 7's new automatic polyfilling behavior.

What it means

Guard in initialize: the site config still sets the legacy `polyfill` option requesting a custom Promise polyfill, which stopped being supported in Gatsby v2 when Babel 7's automatic polyfilling became the only path. The config flag is now meaningless and triggers this warning.

Source

Thrown at packages/gatsby/src/services/initialize.ts:215

  })
  activity.start()
  const flattenedPlugins = await loadPlugins(config, siteDirectory)
  activity.end()

  // GATSBY_QUERY_ON_DEMAND_LOADING_INDICATOR=false gatsby develop
  // to disable query on demand loading indicator
  if (!process.env.GATSBY_QUERY_ON_DEMAND_LOADING_INDICATOR) {
    // if GATSBY_QUERY_ON_DEMAND_LOADING_INDICATOR was not set at all
    // enable loading indicator
    process.env.GATSBY_QUERY_ON_DEMAND_LOADING_INDICATOR = `true`
  }

  if (process.env.GATSBY_DETECT_NODE_MUTATIONS) {
    enableNodeMutationsDetection()
  }

  if (config && config.polyfill) {
    reporter.warn(
      `Support for custom Promise polyfills has been removed in Gatsby v2. We only support Babel 7's new automatic polyfilling behavior.`
    )
  }

  // Throughout the codebase GATSBY_QUERY_ON_DEMAND is used to conditionally enable the QoD behavior, depending on if "gatsby develop" is running or not. In CI QoD is disabled by default, too.
  // You can use GATSBY_ENABLE_QUERY_ON_DEMAND_IN_CI to force enable it in CI.
  process.env.GATSBY_QUERY_ON_DEMAND = `true`
  if (process.env.gatsby_executing_command !== `develop`) {
    // we don't want to ever have this flag enabled for anything than develop
    // in case someone have this env var globally set
    delete process.env.GATSBY_QUERY_ON_DEMAND
  } else if (isCI() && !process.env.GATSBY_ENABLE_QUERY_ON_DEMAND_IN_CI) {
    delete process.env.GATSBY_QUERY_ON_DEMAND
    reporter.verbose(
      `Query on Demand is disabled in CI by default. You can enable it by setting GATSBY_ENABLE_QUERY_ON_DEMAND_IN_CI env var.`
    )
  }

View on GitHub (pinned to e85d62f177)

Solutions

  1. Remove the `polyfill: true` option from gatsby-config.js
  2. Rely on Babel 7's automatic polyfilling instead of a custom Promise polyfill
  3. If legacy browser support is needed, add polyfills via core-js in your own code
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at packages/gatsby/src/services/initialize.ts:215 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/e6de5c5595d43c95. Report an issue: GitHub.