gatsbyjs/gatsby · error · 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

utils.js calculateImageSizes is the entry point for sizing images. It first validates user-supplied width and height: any numeric value < 1 is collected into erroneousUserDimensions and the function throws with a list of the offending key:value pairs. This is the front-door guard before delegating to fixedImageSizes or responsiveImageSizes, and it accepts only positive numbers.

Source

Thrown at packages/gatsby-plugin-sharp/src/utils.js:25

    .slice(1)}`
}

const DEFAULT_PIXEL_DENSITIES = [0.25, 0.5, 1, 2]
const DEFAULT_FLUID_SIZE = 800

const dedupeAndSortDensities = values =>
  Array.from(new Set([1, ...values])).sort()

export function calculateImageSizes(args) {
  const { width, height, file, layout, reporter } = 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 === `fullWidth` || layout === `constrained`) {
    return responsiveImageSizes(args)
  } else {
    reporter.warn(
      `No valid layout was provided for the image at ${file.absolutePath}. Valid image layouts are fixed, fullWidth, and constrained.`
    )
    return []
  }
}

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass positive numbers for width and height: width={400} height={300}.
2. Clamp computed values: const w = Math.max(1, measuredWidth || fallback).
3. Omit width/height if unknown and use layout='fluid'/'constrained'/'fullWidth' to let the plugin compute sizes.

Example fix

// before
<StaticImage src="./hero.jpg" width={0} height={400} />

// after
<StaticImage src="./hero.jpg" width={800} height={400} />

function assertPositiveUserDimensions({ width, height }) {
  const bad = Object.entries({ width, height })
    .filter(([, v]) => typeof v === 'number' && v < 1);
  if (bad.length) throw new Error(`Bad dimensions: ${JSON.stringify(bad)}`);
}

function arePositiveDimensions({ width, height }) {
  return Object.entries({ width, height }).every(([k, v]) =>
    v === undefined || (typeof v === 'number' && v >= 1)
  );
}

When it happens

Trigger: Passing width={0} or height={-1} (or both) to a Gatsby Image component or to the sharp sizes API, e.g. <StaticImage width={0} /> or calculateImageSizes({ width: -10, height: 200, ... }).

Common situations: SSR where a measured width is 0 on first render; user input parsed as number yielding 0; default props that mistakenly set 0; conditional rendering passing through a zeroed measurement.

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 (>
• All ints in srcSetBreakpoints should be positive ints larger
• toFormat seems to be empty, we need a fileExtension to set i

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