gatsbyjs/gatsby · error

replaceRenderer API found in these plugins:

Error message

replaceRenderer API found in these plugins:

What it means

Startup conflict warning: more than one plugin in the flattened list implements the replaceRenderer SSR API, and gatsby only ever calls one renderer — multiple implementations fight over HTML rendering. The warning lists the offending plugin names so the user can remove or guard the extras.

Source

Thrown at packages/gatsby/src/bootstrap/load-plugins/validate.ts:517

  return {
    flattenedPlugins: flattenedPlugins as Array<IFlattenedPlugin>,
    badExports,
  }
}

export const handleMultipleReplaceRenderers = ({
  flattenedPlugins,
}: {
  flattenedPlugins: Array<IFlattenedPlugin>
}): Array<IFlattenedPlugin> => {
  // multiple replaceRenderers may cause problems at build time
  const rendererPlugins = flattenedPlugins
    .filter(plugin => plugin.ssrAPIs.includes(`replaceRenderer`))
    .map(plugin => plugin.name)
  if (rendererPlugins.length > 1) {
    if (rendererPlugins.includes(`default-site-plugin`)) {
      reporter.warn(`replaceRenderer API found in these plugins:`)
      reporter.warn(rendererPlugins.join(`, `))
      reporter.warn(
        `This might be an error, see: https://www.gatsbyjs.com/docs/debugging-replace-renderer-api/`
      )
    } else {
      console.log(``)
      reporter.error(
        `Gatsby's replaceRenderer API is implemented by multiple plugins:`
      )
      reporter.error(rendererPlugins.join(`, `))
      reporter.error(`This will break your build`)
      reporter.error(
        `See: https://www.gatsbyjs.com/docs/debugging-replace-renderer-api/`
      )
      if (process.env.NODE_ENV === `production`) process.exit(1)
    }

    // Now update plugin list so only final replaceRenderer will run

View on GitHub (pinned to e85d62f177)

Solutions

1. Keep only one replaceRenderer implementation — usually your site plugin (gatsby-node.js) or the rendering plugin, not both
2. Guard the export so it only runs for the intended pages/builds
3. Remove the duplicate plugin from gatsby-config.js or wrap with an env check

When it happens

Trigger: Thrown at packages/gatsby/src/bootstrap/load-plugins/validate.ts:517 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/ebbdc2923a092775. Report an issue: GitHub.