Cannot read properties of undefined (reading ‘map’) 완벽 해결법

1. 도입 – React 개발자가 가장 많이 만나는 에러

React 개발을 하다 보면 “Cannot read properties of undefined (reading ‘map’)” 에러를 한 번쯤은 마주하게 됩니다. 이 에러는 특히 API로부터 데이터를 받아와 화면에 렌더링할 때 자주 발생하며, 초보 개발자뿐만 아니라 경험 많은 개발자들도 종종 겪는 문제입니다. 이 에러 메시지는 undefined 상태의 변수에 대해 map() 함수를 호출하려고 할 때 발생하는데, React의 비동기 데이터 처리 특성상 매우 흔하게 나타납니다. 이 글에서는 이 에러가 발생하는 근본적인 원인부터 실전에서 바로 적용할 수 있는 해결방법, 그리고 미래에 이런 에러를 예방하는 베스트 프랙티스까지 모두 다루겠습니다.

2. 에러 상세 분석

“Cannot read properties of undefined (reading ‘map’)” 에러는 JavaScript의 TypeError의 한 종류입니다. 이 에러는 undefined 또는 null 값을 가진 변수에 대해 속성이나 메서드에 접근하려고 할 때 발생합니다. React에서는 주로 배열 데이터를 렌더링하기 위해 map() 메서드를 사용하는데, 이때 배열이 아직 정의되지 않았거나 null 상태일 경우 이 에러가 발생합니다.

이 에러가 발생하는 전형적인 시나리오는 다음과 같습니다. 컴포넌트가 마운트될 때 state의 초기값이 undefined이거나, API 호출이 완료되기 전에 데이터를 렌더링하려고 시도하거나, 잘못된 props 전달로 인해 예상한 배열 데이터가 전달되지 않는 경우입니다. React의 렌더링 사이클은 비동기 작업이 완료되기를 기다리지 않고 즉시 실행되기 때문에, 데이터 로딩 상태를 적절히 처리하지 않으면 이런 에러가 발생할 수밖에 없습니다. 특히 fetch나 axios를 사용한 데이터 페칭 작업에서 자주 나타나며, 에러가 발생하면 화면이 완전히 깨지거나 흰 화면만 표시되는 치명적인 결과를 초래할 수 있습니다.

3. 발생 원인 5가지

3-1. State 초기값 미설정

React의 useState를 사용할 때 초기값을 설정하지 않으면 기본적으로 undefined가 됩니다. 이 상태에서 바로 map()을 호출하면 에러가 발생합니다.

// 잘못된 예시
const [items, setItems] = useState(); // undefined

return (
  

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

3-2. 비동기 데이터 로딩 처리 미흡

API에서 데이터를 받아오는 동안 컴포넌트는 이미 렌더링을 시작합니다. 데이터가 아직 도착하지 않은 상태에서 map()을 실행하면 에러가 발생합니다.

3-3. 잘못된 API 응답 구조

API 응답이 예상한 배열 형태가 아니거나, 중첩된 객체 구조에서 잘못된 경로로 데이터에 접근할 때 undefined를 참조하게 됩니다.

3-4. Props 전달 오류

부모 컴포넌트에서 자식 컴포넌트로 배열 데이터를 전달할 때, props가 제대로 전달되지 않거나 props의 이름이 잘못 지정된 경우 undefined를 참조하게 됩니다.

3-5. 조건부 렌더링 누락

데이터가 존재하는지 확인하는 조건문 없이 바로 map()을 실행하면, 데이터가 없는 상황에서 에러가 발생합니다. 특히 옵셔널 체이닝을 사용하지 않을 경우 더욱 취약합니다.

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

해결법 1: State 초기값을 빈 배열로 설정

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

import { useState, useEffect } from 'react';

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

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

  return (
    

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

해결법 2: 옵셔널 체이닝과 OR 연산자 활용

옵셔널 체이닝(?.)과 논리 OR 연산자(||)를 사용하여 데이터가 없을 때 기본값을 제공합니다.

function ProductList({ products }) {
  return (
    

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

// 또는 옵셔널 체이닝 사용
function OrderList({ data }) {
  return (
    

      {data?.orders?.map(order => (
        
{order.total}
      )) || 
주문 내역이 없습니다.
}
    
  );
}

해결법 3: 조건부 렌더링으로 로딩 상태 처리

데이터가 로딩 중일 때와 로딩 완료 후를 명확히 구분하여 렌더링합니다.

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}
      ))}
    
  );
}

해결법 4: 배열 검증 후 렌더링

Array.isArray()를 사용하여 실제로 배열인지 확인한 후 map()을 실행합니다.

function CommentList({ comments }) {
  return (
    

      {Array.isArray(comments) && comments.length > 0 ? (
        comments.map(comment => (
          
{comment.text}
        ))
      ) : (
        
댓글이 없습니다.
      )}
    
  );
}

해결법 5: try-catch와 에러 바운더리 활용

에러가 발생해도 앱 전체가 중단되지 않도록 에러 처리를 구현합니다.

import { Component } from 'react';

class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  render() {
    if (this.state.hasError) {
      return 
데이터를 불러오는 중 문제가 발생했습니다.
;
    }
    return this.props.children;
  }
}

function App() {
  return (
    
      
  );
}

해결법 6: Default Props 설정

컴포넌트의 기본 props 값을 설정하여 undefined를 방지합니다.

function TaskList({ tasks = [] }) {
  return (
    

      {tasks.map(task => (
        
{task.title}
      ))}
    
  );
}

// 또는 defaultProps 사용
TaskList.defaultProps = {
  tasks: []
};

해결법 7: 커스텀 훅으로 안전한 데이터 페칭

재사용 가능한 커스텀 훅을 만들어 데이터 페칭과 에러 처리를 통합 관리합니다.

function useFetch(url) {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetch(url)
      .then(res => res.json())
      .then(data => {
        setData(Array.isArray(data) ? data : []);
        setLoading(false);
      })
      .catch(err => {
        setError(err);
        setLoading(false);
      });
  }, [url]);

  return { data, loading, error };
}

function PostList() {
  const { data: posts, loading, error } = useFetch('https://api.example.com/posts');

  if (loading) return 
로딩 중...
;
  if (error) return 
에러 발생: {error.message}
;

  return (
    

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

5. 예방법과 베스트 프랙티스

“Cannot read properties of undefined (reading ‘map’)” 에러를 미연에 방지하기 위한 몇 가지 베스트 프랙티스를 소개합니다.

1. 항상 State 초기값 설정: useState를 사용할 때는 반드시 적절한 초기값을 설정하세요. 배열 데이터라면 빈 배열([])을, 객체라면 빈 객체({})를 초기값으로 지정합니다.

2. TypeScript 도입: TypeScript를 사용하면 타입 체크를 통해 컴파일 시점에 이런 에러를 미리 발견할 수 있습니다. 인터페이스와 타입 정의로 데이터 구조를 명확히 하세요.

3. PropTypes 활용: TypeScript를 사용하지 않는다면, PropTypes 라이브러리를 사용하여 props의 타입을 검증할 수 있습니다.

4. 로딩 상태 관리: 모든 비동기 작업에 대해 loading, error, data 세 가지 상태를 관리하는 습관을 들이세요. React Query나 SWR 같은 라이브러리를 사용하면 더욱 쉽게 관리할 수 있습니다.

5. 방어적 프로그래밍: 옵셔널 체이닝, nullish coalescing 연산자 등 최신 JavaScript 문법을 활용하여 안전한 코드를 작성하세요. 데이터 접근 시 항상 존재 여부를 먼저 확인하는 습관을 들이면 많은 에러를 예방할 수 있습니다.

6. 마무리

“Cannot read properties of undefined (reading ‘map’)” 에러는 React 개발에서 매우 흔하게 발생하지만, 원인을 정확히 이해하고 적절한 해결 방법을 적용하면 쉽게 해결할 수 있습니다. 이 글에서 소개한 7가지 해결 방법과 베스트 프랙티스를 실전에 적용하면, 더 이상 이 에러로 고민하지 않아도 됩니다. 특히 State 초기값 설정, 조건부 렌더링, 옵셔널 체이닝 활용은 가장 기본적이면서도 효과적인 방법이니 반드시 숙지하시기 바랍니다. 에러를 두려워하지 말고, 이를 통해 더 견고하고 안정적인 React 애플리케이션을 만들어보세요.