Cannot read properties of undefined (reading ‘map’) 에러 해결 가이드

도입

React 개발 중 “Cannot read properties of undefined (reading ‘map’)” 에러를 만나본 적이 있나요? 이 에러는 React 개발자라면 누구나 한 번쯤 마주치는 흔한 에러입니다. 특히 API로부터 데이터를 받아와 렌더링할 때 자주 발생하는데, 배열이라고 예상한 데이터가 undefined 상태일 때 map 함수를 호출하면서 발생합니다. 이 에러는 애플리케이션을 완전히 멈추게 만들 수 있어 빠른 해결이 필요합니다. 이 글에서는 Cannot read properties of undefined (reading ‘map’) 에러의 원인부터 해결법, 그리고 예방법까지 체계적으로 다루어 여러분이 이 문제를 완벽하게 해결할 수 있도록 돕겠습니다.

에러 상세 분석

이 에러 메시지를 분해해보면 다음과 같은 의미를 담고 있습니다. “Cannot read properties of undefined”는 undefined 값의 속성을 읽을 수 없다는 뜻이고, “(reading ‘map’)”은 구체적으로 map이라는 메서드에 접근하려 했다는 의미입니다. 즉, 배열이어야 할 변수가 undefined 상태인데 그것에 .map() 메서드를 호출하려고 시도했을 때 발생합니다.

이 에러는 런타임 에러로 분류되며, 코드가 실행되는 시점에 발생합니다. 컴파일 타임에는 감지되지 않기 때문에 TypeScript를 사용하더라도 타입 체크가 완벽하지 않으면 발생할 수 있습니다. 브라우저 콘솔에서 이 에러를 확인하면 스택 트레이스를 통해 정확히 어느 컴포넌트의 어느 라인에서 에러가 발생했는지 추적할 수 있습니다. 대부분의 경우 JSX 내부에서 배열을 렌더링하는 부분에서 발생하며, React는 에러 경계(Error Boundary)를 통해 이를 포착할 수 있습니다.

발생 원인 5가지

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

useState나 props로 받은 데이터가 초기에 undefined로 설정되어 있을 때 발생합니다. 컴포넌트가 처음 렌더링될 때 데이터가 아직 로드되지 않았거나, 부모 컴포넌트로부터 props가 전달되지 않은 상태에서 map을 호출하면 이 에러가 발생합니다.

2. API 호출이 완료되기 전 렌더링 시도

비동기 데이터 fetching 과정에서 가장 흔하게 발생하는 원인입니다. useEffect 내에서 API를 호출하고 데이터를 setState로 설정하기 전에 컴포넌트가 먼저 렌더링되면, 데이터가 아직 undefined 상태이므로 에러가 발생합니다.

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

API 응답 데이터의 구조를 잘못 이해하여 발생하는 경우입니다. 예를 들어 data.items.map()을 호출했는데 실제로는 data.results에 배열이 있거나, 중첩된 객체 구조에서 한 단계를 건너뛰어 접근하면 undefined를 반환하게 됩니다.

4. 조건부 렌더링 누락

데이터가 존재하는지 확인하지 않고 바로 map을 호출하는 경우입니다. 특히 옵셔널 체이닝이나 조건부 렌더링 없이 직접 .map()을 호출하면, 데이터가 없는 상황에서 즉시 에러가 발생합니다.

5. Props 전달 오류

부모 컴포넌트에서 자식 컴포넌트로 배열을 전달할 때, prop 이름을 잘못 지정하거나 전달 자체를 누락한 경우입니다. 자식 컴포넌트는 받을 것으로 예상한 배열이 undefined가 되어 에러가 발생합니다.

해결방법 7가지

1. 초기값을 빈 배열로 설정

가장 기본적이고 효과적인 방법입니다. useState의 초기값을 빈 배열([])로 설정하면 컴포넌트 초기 렌더링 시에도 안전하게 map을 호출할 수 있습니다.

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

function UserList() {
  const [users, setUsers] = useState([]); // undefined 대신 빈 배열로 초기화

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

  return (
    

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

2. 옵셔널 체이닝 사용

데이터가 존재하는지 안전하게 확인하면서 접근할 수 있습니다.

function ProductList({ data }) {
  return (
    

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

3. 조건부 렌더링으로 체크

데이터가 존재할 때만 map을 실행하도록 명시적으로 확인합니다.

function CommentList({ comments }) {
  if (!comments || !Array.isArray(comments)) {
    return 
댓글이 없습니다.
;
  }

  return (
    

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

4. 논리 AND 연산자 활용

간결하게 존재 여부를 확인하고 렌더링할 수 있습니다.

function TodoList({ todos }) {
  return (
    

      {todos && todos.map(todo => (
        
{todo.title}
      ))}
    
  );
}

5. defaultProps 사용 (클래스 컴포넌트)

클래스 컴포넌트에서 기본값을 설정하는 방법입니다.

class ItemList extends React.Component {
  static defaultProps = {
    items: []
  };

  render() {
    return (
      

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

6. Nullish Coalescing 연산자 사용

null이나 undefined일 때 기본값을 제공합니다.

function PostList({ posts }) {
  const postList = posts ?? [];
  
  return (
    

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

7. 로딩 상태 관리

데이터 로딩 중임을 사용자에게 명확히 표시합니다.

function ArticleList() {
  const [articles, setArticles] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('https://api.example.com/articles')
      .then(res => res.json())
      .then(data => {
        setArticles(data);
        setLoading(false);
      });
  }, []);

  if (loading) {
    return 
로딩 중...
;
  }

  return (
    

      {articles.map(article => (
        
{article.title}
      ))}
    
  );
}

예방법과 베스트 프랙티스

TypeScript 도입

TypeScript를 사용하면 컴파일 타임에 타입 오류를 미리 잡아낼 수 있습니다. 배열 타입을 명시하면 undefined 가능성을 사전에 파악할 수 있습니다.

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

function UserList({ users }: { users: User[] }) {
  return (
    

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

데이터 구조 검증

API 응답을 받은 후 즉시 콘솔에 출력하여 데이터 구조를 확인하는 습관을 들이세요. Zod나 Yup 같은 스키마 검증 라이브러리를 사용하면 런타임에도 데이터 구조를 안전하게 검증할 수 있습니다.

에러 바운더리 설정

React Error Boundary를 설정하여 예상치 못한 에러가 발생해도 전체 앱이 크래시되지 않도록 보호하세요.

마무리

Cannot read properties of undefined (reading ‘map’) 에러는 React 개발에서 자주 만나는 에러지만, 원인을 정확히 이해하고 적절한 해결책을 적용하면 쉽게 해결할 수 있습니다. 초기값 설정, 조건부 렌더링, 옵셔널 체이닝 등의 방법을 상황에 맞게 활용하고, TypeScript와 같은 도구를 도입하여 사전에 예방하는 것이 중요합니다. 이 글에서 소개한 해결법들을 프로젝트에 적용하여 더 안정적인 React 애플리케이션을 개발하시기 바랍니다. 에러는 학습의 기회이니, 이를 통해 더 나은 개발자로 성장하시길 바랍니다.