gatsbyjs/gatsby · error

No valid layout was provided for the image at ${filename}. V

Error message

No valid layout was provided for the image at ${filename}. Valid image layouts are fixed, fullWidth, and constrained. Found ${layout}

What it means

Layout validation error path in calculateImageSizes: after checking user dimensions are positive numbers, the provided `layout` matched neither `fixed`, `constrained` nor `fullWidth`, so no sizing branch runs and this error identifying the invalid layout value is produced. The layout string usually comes from a <StaticImage> prop or gatsbyImageData layout argument.

Source

Thrown at packages/gatsby-plugin-image/src/image-utils.ts:398

  const erroneousUserDimensions = Object.entries(userDimensions).filter(
    ([_, size]) => typeof size === `number` && size < 1
  )
  if (erroneousUserDimensions.length) {
    throw new Error(
      `Specified dimensions for images must be positive numbers (> 0). Problem dimensions you have are ${erroneousUserDimensions
        .map(dim => dim.join(`: `))
        .join(`, `)}`
    )
  }

  if (layout === `fixed`) {
    return fixedImageSizes(args)
  } else if (layout === `constrained`) {
    return responsiveImageSizes(args)
  } else if (layout === `fullWidth`) {
    return responsiveImageSizes({ breakpoints, ...args })
  } else {
    reporter.warn(
      `No valid layout was provided for the image at ${filename}. Valid image layouts are fixed, fullWidth, and constrained. Found ${layout}`
    )
    return {
      sizes: [imgDimensions.width],
      presentationWidth: imgDimensions.width,
      presentationHeight: imgDimensions.height,
      aspectRatio: imgDimensions.width / imgDimensions.height,
      unscaledWidth: imgDimensions.width,
    }
  }
}
export function fixedImageSizes({
  filename,
  sourceMetadata: imgDimensions,
  width,
  height,
  fit = `cover`,
  outputPixelDensities = DEFAULT_PIXEL_DENSITIES,

View on GitHub (pinned to e85d62f177)

Solutions

1. Pass a valid layout (fixed, constrained or fullWidth) to the image resolver

When it happens

Trigger: Thrown at packages/gatsby-plugin-image/src/image-utils.ts:398 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/16f13ab16c1374cb. Report an issue: GitHub.