Blog

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

React 개발 중 ‘Cannot read properties of undefined (reading ‘map’)’ 에러를 마주치셨나요? 이 에러는 React 개발자들이 가장 흔하게 겪는 런타임 에러 중 하나입니다. 주로 배열 데이터를 렌더링할 때 발생하며, undefined 또는 null 값에 대해 .map() 메서드를 호출하려고 할 때 나타납니다. 이 에러는 특히 API에서 데이터를 가져오는 비동기 작업 중에 자주 발생하며, 초기 렌더링 시점과 데이터 로딩 완료 시점의 차이로 인해 생깁니다. 이 글에서는 이 에러의 원인부터 해결법, 그리고 예방 방법까지 체계적으로 알아보겠습니다.

에러 상세 분석

이 에러 메시지는 JavaScript의 TypeError로 분류되며, 런타임 시점에 발생합니다. 에러가 발생하는 정확한 시점은 undefined 또는 null 값을 가진 변수에 대해 .map() 메서드를 실행하려고 할 때입니다. React 컴포넌트에서는 주로 JSX 내부에서 배열을 렌더링할 때 나타나며, 브라우저 콘솔에는 ‘Cannot read properties of undefined (reading ‘map’)’ 메시지와 함께 에러가 발생한 파일명과 라인 번호가 표시됩니다. 이 에러는 애플리케이션을 완전히 중단시킬 수 있으며, 사용자에게는 빈 화면이나 에러 화면이 보이게 됩니다. 특히 production 환경에서는 사용자 경험을 크게 해치므로 반드시 해결해야 합니다. 에러 스택 트레이스를 확인하면 정확히 어느 컴포넌트의 어느 부분에서 발생했는지 추적할 수 있습니다.

발생 원인 5가지

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

useState를 사용할 때 초기값을 설정하지 않거나 undefined로 설정한 경우 발생합니다. React 컴포넌트가 처음 렌더링될 때 state가 아직 배열이 아닌 상태에서 .map()을 호출하면 에러가 발생합니다.

2. API 데이터 로딩 중인 경우

비동기로 데이터를 가져올 때 가장 흔한 원인입니다. useEffect 내에서 fetch나 axios로 데이터를 가져오는 동안, 컴포넌트는 이미 렌더링되어 undefined 상태의 데이터에 .map()을 시도합니다.

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

부모 컴포넌트로부터 배열 데이터를 props로 받아야 하는데, 실제로는 전달되지 않았거나 undefined가 전달된 경우입니다. 타입스크립트를 사용하지 않으면 이런 실수를 쉽게 놓칠 수 있습니다.

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

API 응답 데이터의 구조를 잘못 이해하여 존재하지 않는 속성에 접근하는 경우입니다. 예를 들어 response.data.items를 기대했지만 실제로는 response.items인 경우 등입니다.

5. 조건부 렌더링 누락

데이터의 존재 여부를 확인하지 않고 바로 .map()을 실행하는 경우입니다. 특히 optional chaining이나 조건문을 사용하지 않았을 때 자주 발생합니다.

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

방법 1: 초기값을 빈 배열로 설정

가장 기본적이고 효과적인 방법입니다. useState의 초기값을 빈 배열로 설정하면 컴포넌트가 처음 렌더링될 때도 .map()이 정상 작동합니다.

import React, { useState } from 'react';

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

  return (
    

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

방법 2: 조건부 렌더링 사용

데이터가 존재할 때만 .map()을 실행하도록 조건을 추가합니다.

function ProductList({ products }) {
  return (
    

      {products && products.length > 0 && products.map(product => (
        
{product.name}
      ))}
    
  );
}

방법 3: Optional Chaining과 Nullish Coalescing 활용

최신 JavaScript 문법을 활용하여 안전하게 배열에 접근합니다.

function CommentList({ data }) {
  const comments = data?.comments ?? [];

  return (
    

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

방법 4: 로딩 상태 관리

데이터 로딩 중임을 명시적으로 표시하여 사용자 경험도 개선합니다.

function DataList() {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('/api/data')
      .then(res => res.json())
      .then(result => {
        setData(result);
        setLoading(false);
      });
  }, []);

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

  return (
    

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

방법 5: Array.isArray() 검증

데이터가 실제로 배열인지 확인한 후 .map()을 실행합니다.

function ItemList({ items }) {
  return (
    

      {Array.isArray(items) && items.map(item => (
        
{item.title}
      ))}
    
  );
}

방법 6: defaultProps 설정 (클래스 컴포넌트)

클래스 컴포넌트에서는 defaultProps를 사용하여 기본값을 설정합니다.

class TaskList extends React.Component {
  static defaultProps = {
    tasks: []
  };

  render() {
    return (
      

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

방법 7: try-catch와 Error Boundary

예상치 못한 에러를 포착하여 앱 전체가 중단되는 것을 방지합니다.

class ErrorBoundary extends React.Component {
  state = { hasError: false };

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

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

// 사용법

  

예방법과 베스트 프랙티스

이 에러를 예방하기 위한 가장 좋은 방법은 TypeScript를 도입하는 것입니다. 타입 시스템이 컴파일 시점에 많은 에러를 잡아줍니다. 또한 항상 state의 초기값을 명확히 설정하고, API 응답 데이터의 구조를 철저히 검증해야 합니다. ESLint와 같은 린터를 사용하여 잠재적인 문제를 사전에 발견할 수 있습니다. 모든 외부 데이터에 대해서는 방어적 프로그래밍을 실천하고, optional chaining과 nullish coalescing 연산자를 적극 활용하세요. PropTypes를 사용하여 props의 타입을 검증하는 것도 좋은 방법입니다. 마지막으로 코드 리뷰 과정에서 이러한 패턴들이 잘 적용되었는지 확인하는 체크리스트를 만들어 두면 팀 전체의 코드 품질을 높일 수 있습니다.

마무리

‘Cannot read properties of undefined (reading ‘map’)’ 에러는 React 개발에서 자주 마주치는 문제이지만, 원인을 이해하고 적절한 방어 코드를 작성하면 충분히 예방할 수 있습니다. 이 글에서 소개한 7가지 해결 방법을 상황에 맞게 적용하고, 베스트 프랙티스를 따른다면 더 이상 이 에러로 고민하지 않아도 될 것입니다. 안전한 코딩 습관을 들여 사용자에게 안정적인 서비스를 제공하시기 바랍니다. 추가로 궁금한 점이 있다면 공식 React 문서를 참고하시거나 개발 커뮤니티에서 도움을 받으실 수 있습니다.