The Next.js Image component requires the alt attribute to be a string for accessibility compliance. This error occurs when the alt prop is missing or explicitly set to undefined, preventing proper screen reader support and fallback text display.
This error is thrown by Next.js when you use the Image component without providing a valid alt attribute, or when the alt prop is explicitly undefined. The Next.js Image component enforces strict accessibility requirements by making the alt attribute mandatory. The alt attribute serves multiple critical purposes: it provides descriptive text for screen readers used by visually impaired users, acts as fallback text when images fail to load, and helps search engines understand image content. Starting with Next.js 13, the framework enforces this requirement at build time and runtime to ensure all images meet web accessibility standards (WCAG). This validation happens during both development and production builds, catching missing or undefined alt props early in the development process. The error is intentional - Next.js prioritizes accessibility by design and won't allow images to be rendered without proper alternative text.
Review your codebase and ensure every Next.js Image component has an alt prop with a string value:
import Image from 'next/image';
// ✅ Correct - descriptive alt text
<Image
src="/profile.png"
alt="User profile picture showing John Smith"
width={500}
height={500}
/>The alt text should meaningfully describe the image content for users who cannot see it.
If an image is purely decorative and provides no meaningful information, use an empty string for the alt attribute:
// ✅ Correct - empty alt for decorative image
<Image
src="/decorative-border.png"
alt=""
width={100}
height={20}
/>This tells screen readers to skip the image, which is the proper accessibility practice for decorative elements.
When setting alt text from variables, ensure they are never undefined:
// ❌ Wrong - alt could be undefined
<Image src={product.image} alt={product.altText} width={300} height={300} />
// ✅ Correct - fallback to meaningful default
<Image
src={product.image}
alt={product.altText || "Product image"}
width={300}
height={300}
/>
// ✅ Better - more specific fallback
<Image
src={product.image}
alt={product.altText || `${product.name} product image`}
width={300}
height={300}
/>Always provide a fallback value that describes the image if the dynamic value is missing.
Next.js includes eslint-plugin-jsx-a11y by default. Ensure it's enabled in your .eslintrc.json:
{
"extends": "next/core-web-vitals"
}This will warn you about missing alt attributes during development:
npm run lintThe linter will catch issues like:
- jsx-a11y/alt-text: Image elements must have an alt prop
For additional type safety, create a wrapper component that enforces alt at the TypeScript level:
// components/SafeImage.tsx
import Image, { ImageProps } from 'next/image';
type SafeImageProps = Omit<ImageProps, 'alt'> & {
alt: string; // Make alt required and non-optional
};
export function SafeImage(props: SafeImageProps) {
return <Image {...props} />;
}Use it in your components:
import { SafeImage } from '@/components/SafeImage';
// TypeScript will enforce alt is provided
<SafeImage src="/logo.png" alt="Company logo" width={200} height={100} />Accessibility Standards: The mandatory alt attribute aligns with WCAG 2.1 Level A requirements (Success Criterion 1.1.1 - Non-text Content). Images must have text alternatives that serve the equivalent purpose.
Empty Alt vs. Missing Alt: There's a critical difference - alt="" tells screen readers "this is decorative, skip it" while missing alt entirely causes screen readers to announce the filename or image path, which is confusing for users.
Alt Text Best Practices:
- Keep alt text under 125 characters when possible
- Avoid starting with "image of" or "picture of" - screen readers already announce it's an image
- For complex images like charts, consider using aria-describedby to reference a longer description
- For images that are also links, describe the destination, not the image
Dynamic Content Patterns: When dealing with user-generated content or CMS data where alt text might be missing, establish a content validation layer that requires alt text before content is published, or generate descriptive alt text from available metadata (filename, title, caption, etc.).
TypeScript Strict Mode: In TypeScript with strict mode enabled, the Next.js Image component types already make alt required. If you're seeing undefined at runtime despite TypeScript passing, check for type assertions or any casts that might be bypassing the type checker.
Migration Strategy: If migrating a large codebase to Next.js Image, use a codemod or search-and-replace to find all Image components and add alt props. You can use grep or your IDE to find instances: grep -r "<Image" --include="*.tsx" --include="*.jsx"
React Hook useCallback has a missing dependency: 'variable'. Either include it or remove the dependency array react-hooks/exhaustive-deps
React Hook useCallback has a missing dependency
Cannot use private fields in class components without TS support
Cannot use private fields in class components without TS support
Cannot destructure property 'xxx' of 'undefined'
Cannot destructure property of undefined when accessing props
useNavigate() may be used only in the context of a <Router> component.
useNavigate() may be used only in the context of a Router component
Cannot find module or its corresponding type declarations
How to fix "Cannot find module or type declarations" in Vite