{"record":{"id":"7a052ca982726338","repo":"gatsbyjs/gatsby","slug":"specified-dimensions-for-images-must-be-positive-n-7a052c","errorCode":null,"errorMessage":"Specified dimensions for images must be positive numbers (> 0). Problem dimensions you have are ${erroneousUserDimensions.map(dim => dim.join(`: `)).join(`, `)}","messagePattern":"Specified dimensions for images must be positive numbers \\(> 0\\)\\. Problem dimensions you have are (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/gatsby-plugin-sharp/src/utils.js","lineNumber":25,"sourceCode":"    .slice(1)}`\n}\n\nconst DEFAULT_PIXEL_DENSITIES = [0.25, 0.5, 1, 2]\nconst DEFAULT_FLUID_SIZE = 800\n\nconst dedupeAndSortDensities = values =>\n  Array.from(new Set([1, ...values])).sort()\n\nexport function calculateImageSizes(args) {\n  const { width, height, file, layout, reporter } = args\n\n  // check that all dimensions provided are positive\n  const userDimensions = { width, height }\n  const erroneousUserDimensions = Object.entries(userDimensions).filter(\n    ([_, size]) => typeof size === `number` && size < 1\n  )\n  if (erroneousUserDimensions.length) {\n    throw new Error(\n      `Specified dimensions for images must be positive numbers (> 0). Problem dimensions you have are ${erroneousUserDimensions\n        .map(dim => dim.join(`: `))\n        .join(`, `)}`\n    )\n  }\n\n  if (layout === `fixed`) {\n    return fixedImageSizes(args)\n  } else if (layout === `fullWidth` || layout === `constrained`) {\n    return responsiveImageSizes(args)\n  } else {\n    reporter.warn(\n      `No valid layout was provided for the image at ${file.absolutePath}. Valid image layouts are fixed, fullWidth, and constrained.`\n    )\n    return []\n  }\n}\n","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby-plugin-sharp/src/utils.js#L7-L43","documentation":"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.","triggerScenarios":"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, ... }).","commonSituations":"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.","solutions":["Pass positive numbers for width and height: width={400} height={300}.","Clamp computed values: const w = Math.max(1, measuredWidth || fallback).","Omit width/height if unknown and use layout='fluid'/'constrained'/'fullWidth' to let the plugin compute sizes."],"exampleFix":"// before\n<StaticImage src=\"./hero.jpg\" width={0} height={400} />\n\n// after\n<StaticImage src=\"./hero.jpg\" width={800} height={400} />","handlingStrategy":"validation","validationCode":"function assertPositiveUserDimensions({ width, height }) {\n  const bad = Object.entries({ width, height })\n    .filter(([, v]) => typeof v === 'number' && v < 1);\n  if (bad.length) throw new Error(`Bad dimensions: ${JSON.stringify(bad)}`);\n}","typeGuard":"function arePositiveDimensions({ width, height }) {\n  return Object.entries({ width, height }).every(([k, v]) =>\n    v === undefined || (typeof v === 'number' && v >= 1)\n  );\n}","tryCatchPattern":null,"preventionTips":["Clamp measured/SSR dimensions to >= 1 with a sensible fallback.","Type width/height props as number and forbid 0 in component propTypes/TS.","Prefer layout='constrained' or 'fullWidth' when exact dimensions are unknown."],"tags":["gatsby-plugin-sharp","image-processing","validation","dimensions"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}