gatsbyjs/gatsby · error · Error

${prop} has to be a positive int larger than zero (> 0), now

Error message

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

What it means

healOptions validates each of width, height, maxWidth, maxHeight: if defined and < 1, it throws. This is the options-level guard (called before the resize pipeline) and complements the runtime check in index.js. It catches 0, negatives, and NaN (since NaN < 1 is false, NaN slips through this guard - the real protection is the parseInt producing NaN leading to a downstream sharp error, but numeric <1 values throw here).

Source

Thrown at packages/gatsby-plugin-sharp/src/plugin-options.ts:223

  if (options.height !== undefined) {
    // @ts-ignore - parseInt as safeguard, expects string tho
    options.height = parseInt(options.height, 10)
  }

  // only set maxWidth to 800 if neither maxWidth nor maxHeight is passed
  if (options.maxWidth === undefined && options.maxHeight === undefined) {
    options.maxWidth = 800
  } else if (options.maxWidth !== undefined) {
    // @ts-ignore - parseInt as safeguard, expects string tho
    options.maxWidth = parseInt(options.maxWidth, 10)
  } else if (options.maxHeight !== undefined) {
    // @ts-ignore - parseInt as safeguard, expects string tho
    options.maxHeight = parseInt(options.maxHeight, 10)
  }

  ;[`width`, `height`, `maxWidth`, `maxHeight`].forEach(prop => {
    if (typeof options[prop] !== `undefined` && options[prop] < 1) {
      throw new Error(
        `${prop} has to be a positive int larger than zero (> 0), now it's ${options[prop]}`
      )
    }
  })
  return options
}

/**
 * Removes all default values so we have the smallest transform args
 */
export const removeDefaultValues = (
  args: ITransformArgs,
  pluginOptions: ISharpPluginOptions
): Partial<ITransformArgs> => {
  const options = {
    height: args.height,
    width: args.width,
    cropFocus: args.cropFocus,

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass only positive numbers for width/height/maxWidth/maxHeight.
2. Validate and clamp before calling: Math.max(1, value) for each.
3. If a dimension is genuinely unknown, omit it (undefined is allowed and skipped).

Example fix

// before
sharp({ file, args: { width: 0, height: 600 } })

// after
sharp({ file, args: { width: 800, height: 600 } })

function assertPositiveDimensions(options) {
  ['width', 'height', 'maxWidth', 'maxHeight'].forEach(prop => {
    if (options[prop] !== undefined && !(Number(options[prop]) >= 1)) {
      throw new Error(`${prop} must be >= 1, got ${options[prop]}`);
    }
  });
}

function hasValidDimensions(options) {
  return ['width', 'height', 'maxWidth', 'maxHeight'].every(prop =>
    options[prop] === undefined || Number(options[prop]) >= 1
  );
}

When it happens

Trigger: Passing width={0}, height={-50}, maxWidth={0}, or maxHeight={-1} to a sharp transform or gatsby-image/StaticImage.

Common situations: Hard-coded placeholders left at 0; computed dimensions from layout math that underflow; CMS fields storing 0 as 'unknown'; unit mismatches producing tiny or negative numbers.

Related errors

• ${fixedDimension} has to be a positive int larger than zero
• Specified dimensions for images must be positive numbers (>
• 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/4906b9460ea362c1. Report an issue: GitHub.