gatsbyjs/gatsby · error

[gatsby-plugin-image] Mismatched image layout: expected "${d

Error message

[gatsby-plugin-image] Mismatched image layout: expected "${defaultImage.layout}" but received "${image.layout}". All art-directed images use the same layout as the default image

What it means

Error "[gatsby-plugin-image] Mismatched image layout: expected "${defaultImage.layout}" but received "${image.layout}". All art-directed images use the same layout as the default image" thrown in gatsbyjs/gatsby.

Source

Thrown at packages/gatsby-plugin-image/src/components/hooks.ts:375

      sources: [],
    },
  }

  artDirected.forEach(({ media, image }) => {
    if (!media) {
      if (process.env.NODE_ENV === `development`) {
        console.warn(
          "[gatsby-plugin-image] All art-directed images passed to must have a value set for `media`. Skipping."
        )
      }
      return
    }

    if (
      image.layout !== defaultImage.layout &&
      process.env.NODE_ENV === `development`
    ) {
      console.warn(
        `[gatsby-plugin-image] Mismatched image layout: expected "${defaultImage.layout}" but received "${image.layout}". All art-directed images use the same layout as the default image`
      )
    }

    output.images.sources.push(
      ...image.images.sources.map(source => {
        return { ...source, media }
      }),
      {
        media,
        srcSet: image.images.fallback.srcSet,
      }
    )

    if (!output.placeholder) {
      return
    }

View on GitHub (pinned to e85d62f177)

Solutions

1. Generate art-directed images with the same layout as the default image (e.g. all constrained)
2. Adjust the default image's layout to match the art-directed ones

When it happens

Trigger: Thrown at packages/gatsby-plugin-image/src/components/hooks.ts:375 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/c753b90d7cd6ed66. Report an issue: GitHub.