{"record":{"id":"c1bad25c024f17cb","repo":"withastro/astro","slug":"missingimagedimension","errorCode":"MissingImageDimension","errorMessage":"Missing ${missingDimension === 'both' ? 'width and height attributes' : `${missingDimension} attribute`} for ${imageURL}. When using remote images, both dimensions are required in order to avoid CLS.","messagePattern":"Missing (.+?) attribute`\\} for (.+?)\\. When using remote images, both dimensions are required in order to avoid CLS\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/assets/services/service.ts","lineNumber":192,"sourceCode":"\t\t) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.LocalImageUsedWrongly,\n\t\t\t\tmessage: AstroErrorData.LocalImageUsedWrongly.message(options.src),\n\t\t\t});\n\t\t}\n\n\t\t// For remote images, width and height are explicitly required as we can't infer them from the file\n\t\tlet missingDimension: 'width' | 'height' | 'both' | undefined;\n\t\tif (!options.width && !options.height) {\n\t\t\tmissingDimension = 'both';\n\t\t} else if (!options.width && options.height) {\n\t\t\tmissingDimension = 'width';\n\t\t} else if (options.width && !options.height) {\n\t\t\tmissingDimension = 'height';\n\t\t}\n\n\t\tif (missingDimension) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.MissingImageDimension,\n\t\t\t\tmessage: AstroErrorData.MissingImageDimension.message(missingDimension, options.src),\n\t\t\t});\n\t\t}\n\t} else {\n\t\tif (!VALID_SUPPORTED_FORMATS.includes(options.src.format as any)) {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.UnsupportedImageFormat,\n\t\t\t\tmessage: AstroErrorData.UnsupportedImageFormat.message(\n\t\t\t\t\toptions.src.format,\n\t\t\t\t\toptions.src.src,\n\t\t\t\t\tVALID_SUPPORTED_FORMATS,\n\t\t\t\t),\n\t\t\t});\n\t\t}\n\n\t\tif (options.widths && options.densities) {\n\t\t\tthrow new AstroError(AstroErrorData.IncompatibleDescriptorOptions);","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/assets/services/service.ts#L174-L210","documentation":"For string (remote) `src`s, `verifyOptions()` requires explicit dimensions because nothing at build time knows the intrinsic size — missing width/height would cause cumulative layout shift (packages/astro/src/assets/services/service.ts:181). One or both missing throws `MissingImageDimension`, naming which attribute(s) are absent.","triggerScenarios":"`<Image src=\"https://cdn.example.com/hero.png\" alt=\"Hero\" />` with no width/height, or with only one of the two; also `getImage({ src: remoteUrl })` without `inferSize`.","commonSituations":"Migrating remote `<img>` tags to `<Image>` and forgetting dimensions; CMS images whose size is only known at runtime; responsive designs assuming auto-sizing.","solutions":["Add both `width` and `height` matching the image's aspect ratio (one can be derived at render time if you know the ratio).","With `getImage()`, set `inferSize: true` (and allowlist the domain) so Astro probes the real dimensions for you.","Better: download the image into `src/` and ESM-import it — dimensions are then read from the file automatically."],"exampleFix":"// before\n<Image src=\"https://cdn.example.com/hero.png\" alt=\"Hero\" />\n\n// after\n<Image src=\"https://cdn.example.com/hero.png\" alt=\"Hero\" width={1200} height={630} />","handlingStrategy":"validation","validationCode":"// for remote string sources, require both dimensions up front\nif (typeof src === 'string' && src.startsWith('http')) {\n  if (!width || !height) {\n    throw new Error(`Remote image ${src} needs both width and height (or inferSize)`);\n  }\n}","typeGuard":"type WithDimensions<T> = T & { width: number; height: number };\n\nfunction hasBothDimensions(o: { width?: number; height?: number }): o is WithDimensions<{}> {\n  return typeof o.width === 'number' && typeof o.height === 'number';\n}","tryCatchPattern":null,"preventionTips":["Store intrinsic width/height alongside remote URLs in CMS schemas.","Prefer importing images locally so dimensions are automatic.","Use inferSize for unknown remote sizes (with the domain allowlisted)."],"tags":["images","image-component","remote-images","cls"],"backgroundTag":"missing-image-dimensions","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}