Couldn't find layout component at "${GATSBY_LAYOUT_COMPONENT

Error message

Couldn't find layout component at "${GATSBY_LAYOUT_COMPONENT_PATH}.

Please create layout component in that location or specify path to layout component in gatsby-config.js

What it means

Thrown by gatsby-plugin-layout's wrap-page.js when requiring GATSBY_LAYOUT_COMPONENT_PATH raises 'Cannot find module'. The plugin defines this webpack global during onCreateWebpackConfig to the resolved layout path; if no file exists there, the synchronous require fails and the wrapper converts it to an actionable message.

Source

Thrown at packages/gatsby-plugin-layout/src/wrap-page.js:9

const React = require(`react`)

const preferDefault = m => (m && m.default) || m
let Layout
try {
  Layout = preferDefault(require(GATSBY_LAYOUT_COMPONENT_PATH))
} catch (e) {
  if (e.toString().indexOf(`Error: Cannot find module`) !== -1) {
    throw new Error(
      `Couldn't find layout component at "${GATSBY_LAYOUT_COMPONENT_PATH}.\n\n` +
        `Please create layout component in that location or specify path to layout component in gatsby-config.js`
    )
  } else {
    // Logging the error for debugging older browsers as there is no way
    // to wrap the thrown error in a try/catch.
    console.error(e)
    throw e
  }
}

// eslint-disable-next-line react/prop-types,react/display-name
module.exports = ({ element, props }) => <Layout {...props}>{element}</Layout>

View on GitHub (pinned to 8b06340921)

Solutions

Create the layout file at src/layouts/index.js (or .jsx) exporting a default React component.
Or set the plugin's `component` option in gatsby-config.js to the actual layout file path.
Verify the path exists with the exact case on case-sensitive filesystems.

Example fix

// gatsby-config.js — before
{ resolve: 'gatsby-plugin-layout', options: { component: 'src/layouts/default' } }
// after
{ resolve: 'gatsby-plugin-layout', options: { component: path.resolve('src/layouts/index.js') } }
// and ensure src/layouts/index.js exports a default component

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs')
if (!fs.existsSync(layoutComponentPath)) {
  console.error(`Layout component missing at ${layoutComponentPath}`)
}

Type guard

const layoutFileExists = (p: string): boolean => { try { return fs.existsSync(p) } catch { return false } }

Prevention

Create src/layouts/index.js before enabling gatsby-plugin-layout.
Set the `component` option to the actual file path.
Verify path case on case-sensitive filesystems.

When it happens

Trigger: Configuring gatsby-plugin-layout (or relying on its default src/layouts/index) but the resolved component file does not exist on disk; the component option points to a missing path; src/layouts/index.[js|jsx] was never created.

Common situations: Defaulting to src/layouts/index but never creating it; renaming/moving the layout file without updating the plugin's component option; using a starter that expected a layout file you deleted; build runs in an environment where the path case differs (case-sensitive FS).

Related errors

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