Blog

React에서 Cannot read properties of undefined (reading ‘map’) 에러란?

React 개발 중 “Cannot read properties of undefined (reading ‘map’)” 에러를 만나본 적이 있나요? 이 에러는 React 개발자들이 가장 자주 마주치는 에러 중 하나입니다. 배열을 렌더링하려고 할 때 데이터가 undefined 상태에서 map 메서드를 호출하면 발생하는 에러로, 초보 개발자부터 숙련된 개발자까지 누구나 겪을 수 있는 문제입니다. 이 글에서는 이 에러의 정확한 원인과 해결 방법, 그리고 예방 전략까지 완벽하게 다루겠습니다. API 호출, 상태 관리, props 전달 과정에서 발생하는 다양한 시나리오를 통해 실전에서 바로 적용할 수 있는 솔루션을 제공합니다.

에러 상세 분석

이 에러 메시지는 JavaScript의 타입 에러(TypeError)로, undefined 또는 null 값에서 ‘map’ 속성을 읽으려고 시도할 때 발생합니다. React에서는 주로 JSX 내부에서 배열 데이터를 렌더링할 때 나타납니다. 예를 들어, users.map()을 실행하려는데 users가 undefined인 상황입니다.

에러가 발생하는 정확한 시점은 렌더링 단계입니다. React 컴포넌트가 화면에 그려지는 과정에서 JSX를 평가할 때, 배열이 아닌 값에 map 메서드를 호출하면 즉시 런타임 에러가 발생하고 애플리케이션이 중단됩니다. 개발 모드에서는 에러 오버레이가 표시되고, 프로덕션에서는 빈 화면이 나타날 수 있습니다.

이 에러는 단순히 코드 실수를 넘어 데이터 흐름의 타이밍 문제, 비동기 처리의 이해 부족, 타입 안정성 결여 등 더 깊은 문제를 나타낼 수 있습니다. 따라서 근본적인 원인을 파악하고 올바른 해결책을 적용하는 것이 중요합니다.

에러 발생 원인 5가지

1. 초기 상태값이 undefined인 경우

useState를 사용할 때 초기값을 설정하지 않거나 undefined로 설정하면, 첫 렌더링 시 map을 호출할 수 없습니다. 특히 API에서 데이터를 가져오기 전 상태가 undefined인 경우가 대표적입니다.

2. API 응답 대기 중

비동기 API 호출의 경우, 데이터가 도착하기 전까지 상태는 초기값 상태입니다. useEffect로 데이터를 fetch하는 동안 컴포넌트는 이미 렌더링을 시도하므로, 데이터가 없는 상태에서 map이 실행됩니다.

3. Props가 전달되지 않은 경우

부모 컴포넌트에서 자식 컴포넌트로 배열 데이터를 props로 전달할 때, 조건부 렌더링이나 데이터 로딩 타이밍 문제로 props가 undefined로 전달될 수 있습니다.

4. 잘못된 데이터 구조 접근

API 응답 구조를 잘못 이해하여 response.data 대신 response를 사용하거나, 중첩된 객체의 경로를 잘못 지정하면 undefined를 얻게 됩니다.

5. 조건부 렌더링 누락

데이터가 로드되기 전 로딩 상태를 처리하지 않고 바로 map을 실행하면, 데이터가 준비되지 않은 상태에서 에러가 발생합니다. 특히 페이지 새로고침 시 상태가 초기화되면서 문제가 생깁니다.

해결방법 7가지 (코드 포함)

방법 1: 초기 상태를 빈 배열로 설정

가장 기본적이고 효과적인 방법입니다. useState의 초기값을 빈 배열로 설정하면 첫 렌더링에서도 map이 안전하게 실행됩니다.

import React, { useState, useEffect } from 'react';

function UserList() {
  const [users, setUsers] = useState([]); // undefined 대신 []

  useEffect(() => {
    fetch('/api/users')
      .then(res => res.json())
      .then(data => setUsers(data));
  }, []);

  return (
    

      {users.map(user => (
        
{user.name}
      ))}
    
  );
}

방법 2: Optional Chaining과 기본값 사용

Optional chaining(?.)과 nullish coalescing(??)를 활용하여 안전하게 데이터에 접근합니다.

function ProductList({ data }) {
  return (
    

      {(data?.products ?? []).map(product => (
        
{product.name}
      ))}
    
  );
}

방법 3: 조건부 렌더링 적용

데이터가 존재하는지 먼저 확인한 후 렌더링합니다. 로딩 상태와 에러 상태도 함께 처리합니다.

function PostList() {
  const [posts, setPosts] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchPosts()
      .then(data => setPosts(data))
      .finally(() => setLoading(false));
  }, []);

  if (loading) return 
로딩 중...
;
  if (!posts) return 
데이터가 없습니다.
;

  return (
    

      {posts.map(post => (
        
{post.title}
      ))}
    
  );
}

방법 4: Array.isArray() 체크

데이터가 실제로 배열인지 확인하는 안전한 방법입니다.

function CommentList({ comments }) {
  return (
    

      {Array.isArray(comments) && comments.map(comment => (
        
{comment.text}
      ))}
    
  );
}

방법 5: 기본 Props 값 설정

컴포넌트에 defaultProps나 기본 매개변수를 설정하여 undefined를 방지합니다.

function ItemList({ items = [] }) {
  return (
    

      {items.map(item => (
        
{item.name}
      ))}
    
  );
}

// 또는 defaultProps 사용
ItemList.defaultProps = {
  items: []
};

방법 6: try-catch로 에러 처리

렌더링 에러를 포착하여 fallback UI를 보여줍니다.

import { ErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error }) {
  return 
오류 발생: {error.message}
;
}

function App() {
  return (
    
      
    
  );
}

방법 7: TypeScript로 타입 안정성 확보

TypeScript를 사용하면 컴파일 시점에 타입 에러를 미리 발견할 수 있습니다.

interface User {
  id: number;
  name: string;
}

interface Props {
  users: User[];
}

function UserList({ users }: Props) {
  return (
    

      {users.map(user => (
        
{user.name}
      ))}
    
  );
}

예방법과 베스트 프랙티스

1. 항상 초기 상태를 적절히 설정하세요. 배열 데이터는 빈 배열([])로, 객체는 빈 객체({})로 초기화합니다.

2. 로딩 상태 관리를 습관화하세요. 비동기 데이터를 다룰 때는 loading, error, data 세 가지 상태를 모두 관리합니다.

3. API 응답 구조를 정확히 파악하세요. console.log로 실제 데이터 구조를 확인하고, 문서를 꼼꼼히 읽습니다.

4. Optional Chaining을 활용하여 중첩된 객체에 안전하게 접근합니다. 특히 외부 API 데이터를 다룰 때 필수입니다.

5. TypeScript 도입을 고려하세요. 타입 시스템이 많은 런타임 에러를 사전에 방지해줍니다.

6. PropTypes나 TypeScript로 Props 검증을 추가하여 잘못된 데이터 전달을 방지합니다.

7. React Query나 SWR 같은 데이터 fetching 라이브러리를 사용하면 로딩, 에러, 캐싱 상태를 자동으로 관리해줍니다.

마무리

“Cannot read properties of undefined (reading ‘map’)” 에러는 React 개발에서 흔하지만, 올바른 이해와 대응 방법을 알면 쉽게 해결할 수 있습니다. 초기 상태 설정, 조건부 렌더링, 타입 체크 등의 방법을 적절히 활용하면 안정적인 애플리케이션을 만들 수 있습니다.

가장 중요한 것은 예방적 코딩입니다. 데이터가 없을 수 있다는 가정 하에 코드를 작성하고, 로딩과 에러 상태를 항상 고려하세요. 이러한 습관이 더욱 견고하고 사용자 친화적인 React 애플리케이션을 만드는 기반이 됩니다. 지금 바로 프로젝트에 적용해보시고, 더 이상 이 에러로 고민하지 마세요!