Blog

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

React 개발을 하다 보면 Cannot read properties of undefined (reading ‘map’) 에러를 자주 마주치게 됩니다. 이 에러는 배열에 map() 메서드를 사용하려고 할 때 해당 변수가 undefined 상태일 때 발생합니다. 특히 API 호출 후 데이터를 렌더링할 때 흔히 나타나는 에러로, React 초보 개발자부터 경력 개발자까지 모두 경험하는 대표적인 런타임 에러입니다. 이 글에서는 이 에러의 원인을 정확히 파악하고, 실무에서 바로 적용 가능한 해결 방법들을 코드 예제와 함께 상세히 알아보겠습니다.

에러 상세 분석

이 에러 메시지를 분석해보면 세 가지 핵심 정보를 담고 있습니다. 첫째, ‘Cannot read properties’는 객체의 속성에 접근하려 했다는 의미입니다. 둘째, ‘of undefined’는 접근하려는 대상이 undefined 상태라는 것을 나타냅니다. 셋째, ‘(reading ‘map’)’은 구체적으로 map 메서드에 접근하려 했음을 보여줍니다.

JavaScript에서 undefined는 변수가 선언되었지만 값이 할당되지 않았거나, 존재하지 않는 속성에 접근할 때 반환되는 원시 값입니다. map()은 배열 전용 메서드이므로, 배열이 아닌 undefined에서 map()을 호출하면 당연히 에러가 발생합니다. React에서는 컴포넌트 렌더링 과정에서 state나 props가 예상과 다르게 undefined일 때 이 문제가 발생합니다. 특히 비동기 데이터 로딩 중에는 데이터가 아직 도착하지 않아 undefined 상태가 될 수 있습니다.

발생 원인 5가지

1. 초기 state 미설정

useState의 초기값을 설정하지 않으면 첫 렌더링 시 undefined가 됩니다. 특히 배열 데이터를 다루는 경우 빈 배열로 초기화하지 않으면 map() 호출 시 즉시 에러가 발생합니다.

2. API 응답 대기 중

비동기 데이터 페칭 시 가장 흔한 원인입니다. API 호출 후 응답이 도착하기 전까지는 데이터가 undefined 상태이며, 이 시점에 렌더링이 시도되면 에러가 발생합니다. useEffect 훅 내에서 데이터를 가져오는 경우 특히 주의해야 합니다.

3. 잘못된 props 전달

부모 컴포넌트에서 자식 컴포넌트로 props를 전달할 때, 예상한 배열 데이터가 전달되지 않거나 속성 이름이 잘못되어 undefined가 전달되는 경우입니다. 타입스크립트를 사용하지 않으면 이런 실수를 런타임에서야 발견하게 됩니다.

4. 객체 구조 분해 오류

중첩된 객체에서 데이터를 추출할 때 중간 경로가 undefined이면 발생합니다. 예를 들어 response.data.items에서 data가 undefined라면 items에 접근할 수 없습니다.

5. 조건부 렌더링 누락

데이터 로딩 상태를 체크하지 않고 바로 map()을 호출하는 경우입니다. 로딩 중이거나 에러 상태일 때도 렌더링을 시도하면 undefined 데이터에 접근하게 됩니다.

해결방법 7가지

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

가장 기본적이고 효과적인 방법입니다. useState 선언 시 빈 배열을 초기값으로 설정하면 첫 렌더링부터 안전하게 map()을 사용할 수 있습니다.

import React, { useState } from 'react';

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

  return (
    

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

방법 2: 옵셔널 체이닝 사용

옵셔널 체이닝(?.)을 사용하면 undefined나 null을 안전하게 처리할 수 있습니다. 배열이 없으면 map()이 실행되지 않습니다.

function ProductList({ products }) {
  return (
    

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

방법 3: 논리 AND 연산자로 조건부 렌더링

데이터가 존재할 때만 렌더링하도록 조건을 추가합니다. 간단하지만 효과적인 방법입니다.

function CommentList({ comments }) {
  return (
    

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

방법 4: 기본값 설정 (Nullish Coalescing)

Nullish coalescing 연산자(??)를 사용하여 undefined나 null일 때 기본값을 제공합니다.

function ItemList({ items }) {
  const itemList = items ?? [];
  
  return (
    

      {itemList.map((item) => (
        
{item.title}
      ))}
    
  );
}

방법 5: 로딩 상태 관리

비동기 데이터를 다룰 때는 로딩 상태를 명시적으로 관리하는 것이 좋습니다. 사용자 경험도 개선됩니다.

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

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

방법 6: Array.isArray() 체크

데이터가 실제로 배열인지 확인한 후 map()을 호출합니다. 타입 안정성이 중요한 경우 유용합니다.

function SafeList({ data }) {
  return (
    

      {Array.isArray(data) && data.map((item) => (
        
{item.content}
      ))}
    
  );
}

방법 7: try-catch와 에러 바운더리

예상치 못한 에러를 방지하기 위해 에러 바운더리를 사용합니다. 프로덕션 환경에서 앱 전체가 멈추는 것을 방지합니다.

class ErrorBoundary extends React.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;
  }
}

// 사용

  

예방법과 베스트 프랙티스

Cannot read properties of undefined (reading ‘map’) 에러를 예방하기 위한 베스트 프랙티스를 소개합니다. 첫째, TypeScript를 도입하여 타입 안정성을 확보하세요. 컴파일 타임에 많은 에러를 사전에 발견할 수 있습니다. 둘째, PropTypes나 defaultProps를 활용하여 props 검증을 추가하세요. 셋째, ESLint 규칙을 설정하여 undefined 체크를 강제하세요. 넷째, 데이터 페칭 시 항상 로딩과 에러 상태를 함께 관리하는 습관을 들이세요. 다섯째, React Query나 SWR 같은 데이터 페칭 라이브러리를 사용하면 이런 문제를 자동으로 처리해줍니다. 여섯째, 코드 리뷰 시 map() 사용 부분을 중점적으로 체크하세요. 일곱째, 단위 테스트를 작성하여 다양한 데이터 상태를 테스트하세요.

마무리

React에서 발생하는 Cannot read properties of undefined (reading ‘map’) 에러는 올바른 초기화와 조건부 렌더링으로 충분히 예방할 수 있습니다. 이 글에서 소개한 7가지 해결 방법을 상황에 맞게 적용하면 안정적인 애플리케이션을 개발할 수 있습니다. 특히 비동기 데이터를 다룰 때는 항상 로딩 상태를 관리하고, TypeScript를 활용하여 타입 안정성을 확보하는 것이 중요합니다. 이제 이 에러를 만나더라도 당황하지 말고 체계적으로 접근하여 해결할 수 있을 것입니다.