gatsbyjs/gatsby · error

Specified dimensions for images must be positive numbers (>

Error message

Specified dimensions for images must be positive numbers (> 0). Problem dimensions you have are ${erroneousUserDimensions.map(dim => dim.join(`: `)).join(`, `)}

What it means

Thrown by calculateImageSizes in gatsby-plugin-image when any user-supplied `width` or `height` is a number less than 1. The pipeline filters dimensions for `typeof size === 'number' && size < 1` and reports each offending pair; negative or zero sizes would break downstream size math, so they are rejected up front.

Source

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

export function calculateImageSizes(args: IImageSizeArgs): IImageSizes {
  const {
    width,
    height,
    filename,
    layout = `constrained`,
    sourceMetadata: imgDimensions,
    reporter = { warn },
    breakpoints = DEFAULT_BREAKPOINTS,
  } = args

  // check that all dimensions provided are positive
  const userDimensions = { width, height }
  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],

View on GitHub (pinned to 8b06340921)

Solutions

1. Coerce or clamp dimensions to a minimum of 1 before passing them in.
2. Trace where the 0/negative value originates (CMS, query, computed ratio) and fix the source.
3. If the dimension is genuinely unknown, omit it and let sourceMetadata drive sizing.
4. Add a guard in your GraphQL resolver or component to fall back to a default when width/height is invalid.

Example fix

// before
<GatsbyImage image={getImage({ ...data, width: 0 })} />
// after
const w = userWidth && userWidth > 0 ? userWidth : undefined
<GatsbyImage image={getImage({ ...data, width: w })} />

const dims = { width, height }
for (const [k, v] of Object.entries(dims)) {
  if (typeof v === 'number' && v < 1) delete dims[k] // let sourceMetadata size instead
}

const arePositiveDimensions = (w?: number, h?: number): boolean =>
  (typeof w !== 'number' || w >= 1) && (typeof h !== 'number' || h >= 1)

When it happens

Trigger: Passing width=0, width=-200, height=0, or fractional sub-pixel values to calculateImageSizes/generateImageData (e.g. via the <GatsbyImage> component's width/height or the GraphQL gatsbyImageData arguments). Any one bad dimension triggers the throw.

Common situations: Computing width/height from a CMS field that occasionally returns 0 for an empty image; passing a CSS-derived fractional pixel value; typos negating a dimension; responsive math producing 0 for tiny viewports.

Related errors

• ${fixedDimension} has to be a positive int larger than zero
• ${prop} has to be a positive int larger than zero (> 0), now
• Specified dimensions for images must be positive numbers (>
• generateImageSource must be a function
• All ints in srcSetBreakpoints should be positive ints larger

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