You can only have single instance of gatsby-plugin-layout in

Error message

You can only have single instance of gatsby-plugin-layout in your gatsby-config.js

What it means

Thrown by gatsby-plugin-layout's onPreInit when the plugin's module-level didRunAlready flag is already true, i.e. onPreInit has executed once already in this Node process. The plugin stores absoluteComponentPath in module scope, so a second initialization would overwrite it; the guard hard-blocks duplicate registration.

Source

Thrown at packages/gatsby-plugin-layout/src/gatsby-node.js:17

const path = require(`path`)

let didRunAlready = false
let absoluteComponentPath

exports.onPreInit = ({ store }, { component }) => {
  const defaultLayoutComponentPath = `src/layouts/index`
  if (!component) {
    // Default to `src/layouts/index.[js|jsx]` for drop-in replacement of v1 layouts
    component = path.join(
      store.getState().program.directory,
      defaultLayoutComponentPath
    )
  }

  if (didRunAlready) {
    throw new Error(
      `You can only have single instance of gatsby-plugin-layout in your gatsby-config.js`
    )
  }

  didRunAlready = true
  absoluteComponentPath = component
}

exports.onCreateWebpackConfig = ({ actions, plugins }) => {
  actions.setWebpackConfig({
    plugins: [
      plugins.define({
        GATSBY_LAYOUT_COMPONENT_PATH: JSON.stringify(absoluteComponentPath),
      }),
    ],
  })
}

View on GitHub (pinned to 8b06340921)

Solutions

Search gatsby-config.js (and any presets/themes) for duplicate gatsby-plugin-layout entries and keep only one.
Run `gatsby plugin` to list resolved plugins and confirm the plugin appears once.
If a theme brings it in, remove your own explicit entry and let the theme own it.

Example fix

// before (duplicate entry)
plugins: ['gatsby-plugin-layout', { resolve: 'gatsby-theme-x', options: {} }, 'gatsby-plugin-layout']
// after (single entry)
plugins: ['gatsby-plugin-layout', { resolve: 'gatsby-theme-x', options: {} }]

Defensive patterns

Strategy: validation

Validate before calling

const layoutPlugins = plugins.filter(p => (typeof p === 'string' ? p : p.resolve) === 'gatsby-plugin-layout')
if (layoutPlugins.length > 1) throw new Error('duplicate gatsby-plugin-layout')

Type guard

const isSingleLayoutPlugin = (plugins: any[]): boolean =>
  plugins.filter(p => (typeof p === 'string' ? p : p?.resolve) === 'gatsby-plugin-layout').length === 1

Prevention

List gatsby-plugin-layout exactly once in gatsby-config.js.
Run `gatsby plugin` to confirm no duplicates from themes.
Let a theme own the plugin instead of re-adding it.

When it happens

Trigger: Listing gatsby-plugin-layout more than once in the plugins array of gatsby-config.js; including a starter or theme that itself adds gatsby-plugin-layout while you also list it; a composite config (gatsby-config + .gatsby-config presets) that merges the plugin in twice.

Common situations: User adds gatsby-plugin-layout manually while a theme (e.g. a blog theme) already depends on it; copying config snippets from docs without checking duplicates; upgrading a theme that newly added the plugin.

Related errors

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