gatsbyjs/gatsby · error · Error

The provided width of "${width}" is incorrect. Dimensions sh

Error message

The provided width of "${width}" is incorrect. Dimensions should be a positive number.

What it means

Thrown by calculateImageSizes in the polyfill-remote-file image utils when a `width` value is provided but is not a positive number (zero or negative). The width must be > 0 because sharp and the image service require valid target dimensions.

Source

Thrown at packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/gatsby-image-resolver.ts:418

): string {
  return images.map(image => `${image.src} ${image.descriptor}`).join(`,`)
}

// eslint-disable-next-line consistent-return
function calculateImageSizes(
  sourceMetadata: ISourceMetadata,
  {
    width,
    height,
    layout,
    fit,
    outputPixelDensities,
    breakpoints,
    aspectRatio,
  }: CalculateImageSizesArgs
): IImageSizes {
  if (width && Number(width) <= 0) {
    throw new Error(
      `The provided width of "${width}" is incorrect. Dimensions should be a positive number.`
    )
  }

  if (height && Number(height) <= 0) {
    throw new Error(
      `The provided height of "${height}" is incorrect. Dimensions should be a positive number.`
    )
  }

  switch (layout) {
    case `fixed`: {
      return calculateFixedImageSizes({
        width,
        height,
        fit,
        sourceMetadata,
        outputPixelDensities,

View on GitHub (pinned to 8b06340921)

Solutions

1. Ensure width is a positive integer greater than 0 (e.g., 200, 800).
2. Validate computed width values before passing them to the resolver — guard against 0 or negative results from layout calculations.
3. If width comes from user input, sanitize it to a minimum positive value (e.g., Math.max(1, width)).
4. Remove the width argument entirely and provide height instead if only height is known.

Example fix

// before
gatsbyImageResolver(source, { layout: 'fixed', width: 0 })
// after
gatsbyImageResolver(source, { layout: 'fixed', width: 300 })

// Sanitize width before passing to calculateImageSizes
if (width !== undefined && width !== null) {
  const numericWidth = Number(width)
  if (!Number.isFinite(numericWidth) || numericWidth <= 0) {
    throw new Error(`width must be a positive number, got ${width}`)
  }
}

const isPositiveDimension = (val: unknown): val is number =>
  typeof val === 'number' && val > 0 && Number.isFinite(val)

When it happens

Trigger: width is truthy but Number(width) <= 0; this catches width: 0, width: -100, or width as a string that coerces to a non-positive number.

Common situations: A query passes width: 0 by mistake, a computed width from CSS/JS evaluates to zero or negative, or width is passed as an invalid string like '-5'.

Related errors

• The provided height of "${height}" is incorrect. Dimensions
• Either the "width" or "height" argument is required f
• No width or height is given to resize "${source.url}"
• The "layout" argument is required for "${source.url}"
• Unknown format "${args.format}" was given to resize ${source

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