gatsbyjs/gatsby · error

Specifying fullWidth images will ignore the width and height

Error message

Specifying fullWidth images will ignore the width and height arguments, you may want a constrained image instead. Otherwise, use the breakpoints argument.

What it means

generateImageData warning: width/height were passed together with a fullWidth layout, whose sizes derive from breakpoints instead; the passed width is overwritten with the source width and height cleared, so the user values have no effect.

Source

Thrown at packages/gatsby-plugin-sharp/src/image-data.ts:178

    fit = `cover`,
    cropFocus = sharp.strategy.attention,
    duotone,
  } = transformOptions

  if (duotone && (!duotone.highlight || !duotone.shadow)) {
    reporter.warn(
      `Invalid duotone option specified for ${file.absolutePath}, ignoring. Please pass an object to duotone with the keys "highlight" and "shadow" set to the corresponding hex values you want to use.`
    )
  }

  const metadata = await getImageMetadata(
    file,
    placeholder === `dominantColor`,
    cache
  )

  if ((args.width || args.height) && layout === `fullWidth`) {
    reporter.warn(
      `Specifying fullWidth images will ignore the width and height arguments, you may want a constrained image instead. Otherwise, use the breakpoints argument.`
    )
    args.width = metadata?.width
    args.height = undefined
  }

  if (!args.width && !args.height && metadata.width) {
    args.width = metadata.width
  }

  if (args.aspectRatio) {
    if (args.width && args.height) {
      reporter.warn(
        `Specifying aspectRatio along with both width and height will cause aspectRatio to be ignored.`
      )
    } else if (args.width) {
      args.height = args.width / args.aspectRatio
    } else if (args.height) {

View on GitHub (pinned to e85d62f177)

Solutions

1. Use layout "constrained" or "fixed" when you need explicit dimensions
2. For fullWidth, control sizes via the breakpoints argument instead

When it happens

Trigger: Thrown at packages/gatsby-plugin-sharp/src/image-data.ts:178 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/f937dfc4aaaee060. Report an issue: GitHub.