How to fix Image with src="%s" was missing required "alt" property in React

ReactBEGINNERMEDIUMUpdated Dec 9, 2025· 117 views

Next.js requires all Image components to include an alt attribute for accessibility compliance. This error occurs when you use the next/image component without providing the alt prop, preventing proper screen reader support and accessibility standards.

Quick fix

Fixes Image with src="%s" was missing required "alt" property

import Image from 'next/image';

// Before (causes error)
<Image src="/profile.jpg" width={200} height={200} />

// After (fixed)
<Image
  src="/profile.jpg"
  width={200}
  height={200}
  alt="User profile photo showing person smiling"
/>
  1. Add descriptive alt text to your Image component
  2. Use empty string for purely decorative images
  3. Handle dynamic images with conditional alt text
  4. Update TypeScript types for image props
react — error
import Image from 'next/image';
// Before (causes error)
<Image src="/profile.jpg" width={200} height={200} />
// After (fixed)
<Image
  src="/profile.jpg"
  width={200}
  height={200}
  alt="User profile photo showing person smiling"
/>
Image with src="%s" was missing required "alt" property

What this error means

This error is thrown by Next.js when you use the `<Image>` component without including the required `alt` property. The Next.js Image component enforces accessibility best practices by making the alt attribute mandatory, unlike standard HTML img elements where it's technically optional but recommended. The alt (alternative text) attribute serves multiple critical purposes: it provides text descriptions for screen readers used by visually impaired users, displays fallback text when images fail to load, and helps search engines understand image content for SEO. Next.js takes a strict approach to accessibility by refusing to render images without this property. This is an intentional design decision by the Next.js team to encourage developers to build more accessible applications by default. The framework goes beyond W3C recommendations by enforcing what is merely a "should" in the HTML specification as a hard requirement.

Typical symptoms

  • Build fails with error message about missing alt property
  • Development server shows error overlay highlighting the Image component
  • TypeScript shows type error on Image component when alt is omitted
  • Console warnings in development mode pointing to specific Image usage
  • Image fails to render in the browser during development

Common causes

  1. Forgetting to add the alt prop when using Next.js Image component
  2. Copying code from standard HTML img elements that omit alt
  3. Migrating from regular img tags to next/image without updating all properties
  4. Dynamic image rendering where alt prop is conditionally undefined or null
  5. Using spread props that don't include an alt property
  6. Template or component library not passing alt through to Image component

How to fix "Image with src="%s" was missing required "alt" property"

1Add descriptive alt text to your Image component

Locate the Image component showing the error and add a meaningful alt attribute that describes the image content:

tsx
import Image from 'next/image';

// Before (causes error)
<Image src="/profile.jpg" width={200} height={200} />

// After (fixed)
<Image
  src="/profile.jpg"
  width={200}
  height={200}
  alt="User profile photo showing person smiling"
/>

The alt text should be descriptive and convey the meaning or purpose of the image. Avoid generic descriptions like "image" or "photo".

2Use empty string for purely decorative images

If the image is purely decorative and doesn't convey meaningful information (like background patterns, dividers, or aesthetic elements), use an empty string for the alt attribute:

tsx
<Image
  src="/decorative-pattern.svg"
  width={100}
  height={100}
  alt=""
/>

This tells screen readers to skip the image entirely, which is the correct accessibility behavior for decorative content. Never omit the alt prop completely—always use alt="" for decorative images.

3Handle dynamic images with conditional alt text

For dynamically loaded images, ensure the alt prop is always defined, even if it comes from your data source:

tsx
interface Product {
  imageUrl: string;
  name: string;
  altText?: string;
}

function ProductImage({ product }: { product: Product }) {
  return (
    <Image
      src={product.imageUrl}
      width={300}
      height={300}
      alt={product.altText || product.name || 'Product image'}
    />
  );
}

Always provide a fallback value to ensure alt is never undefined or null.

4Update TypeScript types for image props

If you're passing image props through component hierarchies, ensure your TypeScript interfaces include the alt property:

tsx
interface ImageProps {
  src: string;
  alt: string; // Required, not optional
  width?: number;
  height?: number;
}

function CustomImage({ src, alt, width = 500, height = 500 }: ImageProps) {
  return <Image src={src} alt={alt} width={width} height={height} />;
}

Making alt required in your own types prevents accidentally passing incomplete props to Next.js Image components.

Advanced notes

Why Next.js enforces alt text:

Next.js makes the alt attribute required as part of its philosophy of "pit of success" design—making the correct, accessible approach the easiest path. While HTML specifications technically allow images without alt attributes, this creates accessibility barriers and violates WCAG 2.1 guidelines.

Screen reader behavior:

When an image lacks alt text, screen readers often fall back to reading the image filename, which can be confusing ("IMG_20230415_final_v2.jpg") or meaningless to users. By requiring alt text, Next.js ensures all images are either properly described or explicitly marked as decorative.

SEO implications:

Search engines use alt text as a ranking signal for image search and to understand page content context. Images with proper alt text contribute to better SEO performance and improved content discoverability.

ESLint integration:

The eslint-plugin-jsx-a11y package (included in Next.js by default) provides additional checks for alt text quality beyond just presence. Consider enabling rules like jsx-a11y/alt-text for more comprehensive accessibility linting.

Migration strategies:

When migrating large codebases from img to Image components, use find-and-replace with regex to systematically add alt props. Search for <Image[^>]*src= patterns and audit each usage for appropriate alt text rather than adding placeholder values.

Performance considerations:

The alt attribute has no impact on image loading performance or optimization features. Next.js Image optimization (automatic WebP/AVIF conversion, lazy loading, responsive sizing) works identically regardless of alt text content.

Frequently asked questions

What does "Image with src="%s" was missing required "alt" property" mean?
js when you use the <Image> component without including the required alt property. js Image component enforces accessibility best practices by making the alt attribute mandatory, unlike standard HTML img elements where it's technically optional but recommended. The alt (alternative text) attribute serves multiple critical purposes: it provides text descriptions for screen readers used by visually impaired users, displays fallback text when images fail to load, and helps search engines understand image content for SEO.
How do I fix "Image with src="%s" was missing required "alt" property"?
Next.js requires all Image components to include an alt attribute for accessibility compliance. This error occurs when you use the next/image component without providing the alt prop, preventing proper screen reader support and accessibility standards.
What causes "Image with src="%s" was missing required "alt" property"?
Forgetting to add the alt prop when using Next.js Image component Copying code from standard HTML img elements that omit alt Migrating from regular img tags to next/image without updating all properties
Is the "Image with src="%s" was missing required "alt" property" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading