{"record":{"id":"31cda7b7fb848b0c","repo":"withastro/astro","slug":"imagemissingalt","errorCode":"ImageMissingAlt","errorMessage":"Image missing \"alt\" property. \"alt\" text is required to describe important images on the page.","messagePattern":"Image missing \"alt\" property\\. \"alt\" text is required to describe important images on the page\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/components/Image.astro","lineNumber":15,"sourceCode":"---\nimport { getImage, imageConfig, type LocalImageProps, type RemoteImageProps } from 'astro:assets';\nimport type { UnresolvedImageTransform } from '../dist/assets/types.js';\nimport { AstroError, AstroErrorData } from '../dist/core/errors/index.js';\nimport type { HTMLAttributes } from '../types.js';\n\n// The TypeScript diagnostic for JSX props uses the last member of the union to suggest props, so it would be better for\n// LocalImageProps to be last. Unfortunately, when we do this the error messages that remote images get are complete nonsense\n// Not 100% sure how to fix this, seems to be a TypeScript issue. Unfortunate.\ntype Props = LocalImageProps | RemoteImageProps;\n\nconst props = Astro.props;\n\nif (props.alt === undefined || props.alt === null) {\n\tthrow new AstroError(AstroErrorData.ImageMissingAlt);\n}\n\n// As a convenience, allow width and height to be string with a number in them, to match HTML's native `img`.\nif (typeof props.width === 'string') {\n\tprops.width = Number.parseInt(props.width);\n}\n\nif (typeof props.height === 'string') {\n\tprops.height = Number.parseInt(props.height);\n}\n\nconst layout = props.layout ?? imageConfig.layout ?? 'none';\n\nif (layout !== 'none') {\n\tprops.layout ??= imageConfig.layout;\n\tprops.fit ??= imageConfig.objectFit ?? 'cover';\n\tprops.position ??= imageConfig.objectPosition ?? 'center';\n} else if (imageConfig.objectFit || imageConfig.objectPosition) {","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/components/Image.astro#L1-L33","documentation":"The built-in `<Image />` component treats `alt` as mandatory and throws `ImageMissingAlt` at render time when the prop is `undefined` or `null`. This is an accessibility guard: every `<img>` needs alt text, so the component refuses to render without it. Empty-string alt (`alt=\"\"`) is accepted and marks the image decorative.","triggerScenarios":"Rendering `<Image src={...} width={...} height={...} />` with no `alt`; passing `alt={undefined}` because the variable powering it is not set (e.g. `alt={post.altText}` where altText is missing from CMS data); spreading props from an object without alt.","commonSituations":"CMS entries lacking an alt field that flows straight into the component; refactoring from plain `<img>` (where missing alt only warns) to `<Image>`; conditional props where alt is accidentally dropped.","solutions":["Add descriptive alt text: `<Image src={hero} alt=\"Team standing in front of the new office\" />`","For decorative images pass an explicit empty string: `alt=\"\"`","When alt comes from data, provide a fallback: `alt={post.altText ?? post.title}`"],"exampleFix":"// before\n<Image src={hero} width={800} height={600} />\n\n// after\n<Image src={hero} width={800} height={600} alt=\"Product screenshot of the dashboard\" />","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"function hasAlt(props: { alt?: string | null }): boolean {\n  return props.alt != null;\n}","tryCatchPattern":null,"preventionTips":["Always write alt alongside src when adding <Image>","Fallback at the data boundary: `alt={img.altText ?? img.title ?? ''}`","Enable a11y lint rules (jsx-a11y/alt-text) to catch missing alt before runtime"],"tags":["image","accessibility","alt-text","component"],"backgroundTag":"missing-alt-attribute","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}