gatsbyjs/gatsby · error · Error

${fixedDimension} has to be a positive int larger than zero

Error message

${fixedDimension} has to be a positive int larger than zero (> 0), now it's ${options[fixedDimension]}

What it means

In gatsby-plugin-sharp's fluidImageSizes / fixedImage pipeline, the code selects which dimension is the controlling one (maxWidth, or maxHeight when maxWidth is undefined) and validates that it is >= 1. Values of 0, negative numbers, or NaN (e.g. from a non-numeric string coerced via arithmetic) trip the check. The dimension must be a positive integer larger than zero.

Source

Thrown at packages/gatsby-plugin-sharp/src/index.js:452

      reporter
    )
    return null
  }

  const { width, height, density, format } = metadata

  // if no maxWidth is passed, we need to resize the image based on the passed maxHeight
  const fixedDimension =
    options.maxWidth === undefined ? `maxHeight` : `maxWidth`
  const maxWidth = options.maxWidth
    ? Math.min(options.maxWidth, width)
    : undefined
  const maxHeight = options.maxHeight
    ? Math.min(options.maxHeight, height)
    : undefined

  if (options[fixedDimension] < 1) {
    throw new Error(
      `${fixedDimension} has to be a positive int larger than zero (> 0), now it's ${options[fixedDimension]}`
    )
  }

  // Create sizes (in width) for the image if no custom breakpoints are
  // provided. If the max width of the container for the rendered markdown file
  // is 800px, the sizes would then be: 200, 400, 800, 1200, 1600.
  //
  // This is enough sizes to provide close to the optimal image size for every
  // device size / screen resolution while (hopefully) not requiring too much
  // image processing time (Sharp has optimizations thankfully for creating
  // multiple sizes of the same input file)
  const fluidSizes = [
    options[fixedDimension], // ensure maxWidth (or maxHeight) is added
  ]
  // use standard breakpoints if no custom breakpoints are specified
  if (!options.srcSetBreakpoints || !options.srcSetBreakpoints.length) {
    fluidSizes.push(options[fixedDimension] / 4)

View on GitHub (pinned to 8b06340921)

Solutions

Pass a positive integer, e.g. maxWidth={800} (the plugin default).
Coerce and clamp user/SSR input before calling: const w = Math.max(1, parseInt(rawWidth, 10) || 800).
If you genuinely want unconstrained width, use layout='fullWidth' instead of setting maxWidth to 0.

Example fix

// before
<StaticImage src="./hero.jpg" maxWidth={0} />

// after
<StaticImage src="./hero.jpg" layout="fullWidth" />
// or
<StaticImage src="./hero.jpg" maxWidth={800} />

Defensive patterns

Strategy: validation

Validate before calling

function assertFixedDimension(options) {
  const key = options.maxWidth === undefined ? 'maxHeight' : 'maxWidth';
  const v = Number(options[key]);
  if (!Number.isInteger(v) || v < 1) {
    throw new Error(`${key} must be a positive integer > 0, got ${options[key]}`);
  }
}

Type guard

function isPositiveFixedDimension(options) {
  const key = options.maxWidth === undefined ? 'maxHeight' : 'maxWidth';
  const v = Number(options[key]);
  return Number.isInteger(v) && v > 0;
}

Prevention

Default maxWidth/maxHeight to a sane positive constant (e.g. 800).
Clamp SSR/computed widths: Math.max(1, Math.floor(value)).
Use layout='fullWidth' instead of maxWidth={0} when you want fluid width.

When it happens

Trigger: Passing maxWidth={0}, maxWidth={-100}, or a non-numeric maxWidth to the fluid/resize sharp API or to gatsby-image/StaticImage, e.g. <StaticImage maxWidth={0} /> or sharp({ maxWidth: 'abc' }).

Common situations: Computing maxWidth from a CSS variable or window width that is 0 during SSR; passing a prop that defaults to 0; user-uploaded width parsed as string; conditional that yields undefined-then-NaN.

Related errors

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