gatsbyjs/gatsby · error

This might be an error, see: https://www.gatsbyjs.com/docs/d

Error message

This might be an error, see: https://www.gatsbyjs.com/docs/debugging-replace-renderer-api/

What it means

Trailing hint of the warning emitted by handleMultipleReplaceRenderers when more than one plugin implements the replaceRenderer SSR API, which produces conflicting renderers at build time; the doc link explains how to identify which plugin to keep.

Source

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

    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
    const ignorable = rendererPlugins.slice(0, -1)

View on GitHub (pinned to e85d62f177)

Solutions

1. Remove or disable all but one replaceRenderer implementation (usually keeping the default-site-plugin's)

When it happens

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