How to fix Expected node.alt to be "string" but found "undefined" in React

ReactBEGINNERMEDIUMUpdated Dec 9, 2025· 85 views

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.

Quick fix

Fixes Expected node.alt to be "string" but found "undefined"

import Image from 'next/image';

// ✅ Correct - descriptive alt text
<Image
  src="/profile.png"
  alt="User profile picture showing John Smith"
  width={500}
  height={500}
/>
  1. Add alt prop to all Image components
  2. Use empty string for decorative images
  3. Provide fallback values for dynamic alt text
  4. Enable ESLint accessibility rules
react — error
import Image from 'next/image';
// ✅ Correct - descriptive alt text
<Image
  src="/profile.png"
  alt="User profile picture showing John Smith"
  width={500}
  height={500}
/>
Expected node.alt to be "string" but found "undefined"

What this error means

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.

Typical symptoms

  • Build fails with "Expected node.alt to be string but found undefined" error
  • Development server throws type error when rendering Image components
  • ESLint warnings about missing alt text on Image components
  • TypeScript compilation errors if alt prop is not provided
  • Console errors in browser when Image component renders without alt

Common causes

  1. Forgot to include the alt prop on a Next.js Image component
  2. Passing undefined as the alt prop value explicitly
  3. Dynamically setting alt from a variable that may be undefined
  4. Conditionally rendering Image without ensuring alt is always defined
  5. Copying code examples that omit the alt attribute
  6. Migrating from standard img tags to Next.js Image without adding alt props

How to fix "Expected node.alt to be "string" but found "undefined""

1Add alt prop to all Image components

Review your codebase and ensure every Next.js Image component has an alt prop with a string value:

jsx
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.

2Use empty string for decorative images

If an image is purely decorative and provides no meaningful information, use an empty string for the alt attribute:

jsx
// ✅ 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.

3Provide fallback values for dynamic alt text

When setting alt text from variables, ensure they are never undefined:

jsx
// ❌ 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.

4Enable ESLint accessibility rules

Next.js includes eslint-plugin-jsx-a11y by default. Ensure it's enabled in your .eslintrc.json:

json
{
  "extends": "next/core-web-vitals"
}

This will warn you about missing alt attributes during development:

bash
npm run lint

The linter will catch issues like:
- jsx-a11y/alt-text: Image elements must have an alt prop

5Create a typed wrapper component (optional)

For additional type safety, create a wrapper component that enforces alt at the TypeScript level:

tsx
// 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:

tsx
import { SafeImage } from '@/components/SafeImage';

// TypeScript will enforce alt is provided
<SafeImage src="/logo.png" alt="Company logo" width={200} height={100} />

Advanced notes

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"

Frequently asked questions

What does "Expected node.alt to be "string" but found "undefined"" mean?
js when you use the Image component without providing a valid alt attribute, or when the alt prop is explicitly undefined. 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.
How do I fix "Expected node.alt to be "string" but found "undefined""?
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.
What causes "Expected node.alt to be "string" but found "undefined""?
Forgot to include the alt prop on a Next.js Image component Passing undefined as the alt prop value explicitly Dynamically setting alt from a variable that may be undefined
Is the "Expected node.alt to be "string" but found "undefined"" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading