{"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/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/components/Image.astro#L1-L33","documentation":"AstroError with code `ImageMissingAlt`, thrown by the `<Image>` component when the `alt` prop is `undefined` or `null`. Astro requires `alt` on every image for accessibility (screen readers and assistive tech); decorative images must explicitly pass `alt=\"\"`. The error is thrown before any image transform happens, so it fails at render time of any `<Image>` call missing the prop.","triggerScenarios":"Calling `<Image src={...} />` without an `alt` prop; destructuring props and conditionally leaving `alt` unset; passing `alt={undefined}` or `alt={null}`; migrating from plain `<img>` and forgetting the prop.","commonSituations":"A developer drops in `<Image>` from a migration or template and omits `alt`; CMS-driven content where `alt` is optional and arrives undefined; conditional rendering that forgets the `alt` branch.","solutions":["Add a descriptive `alt` prop: `<Image src={img} alt=\"A red fox in the snow\" />`.","For decorative images, pass an empty string explicitly: `<Image src={img} alt=\"\" />`.","For dynamic/CMS content, default or guard the value: `alt={data.alt ?? ''}`.","Run `astro check` to catch missing-prop cases during development."],"exampleFix":"// before\n<Image src={hero} />\n\n// after\n<Image src={hero} alt=\"Hero illustration of the product\" />","handlingStrategy":"type-guard","validationCode":"type ImageProps = { alt: string } & Record<string, unknown>;\nfunction hasAlt(props: unknown): props is ImageProps {\n  return typeof (props as any)?.alt === 'string';\n}\n// before rendering\nif (!hasAlt(props)) props.alt = ''; // or throw a friendlier error","typeGuard":"function hasAltProp(props: unknown): props is { alt: string } {\n  return props != null && typeof (props as { alt?: unknown }).alt === 'string';\n}","tryCatchPattern":null,"preventionTips":["Treat `alt` as required in your content schemas/CMS.","Default dynamic alt to '' for decorative images: `alt={data.alt ?? ''}`.","Run `astro check` in CI to catch missing required props.","Codemod `<img>` migrations to always carry `alt` over."],"tags":["astro-component","image","accessibility","a11y","required-prop"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}