React에서 Cannot read properties of undefined (reading ‘map’) 에러 완벽 해결하기

1. 도입

React 개발을 하다 보면 “Cannot read properties of undefined (reading ‘map’)” 에러를 자주 마주치게 됩니다. 이 에러는 React 초보 개발자뿐만 아니라 숙련된 개발자들도 흔히 겪는 문제입니다. 특히 API 호출 결과를 렌더링하거나 배열 데이터를 처리할 때 빈번하게 발생합니다. 이 에러는 undefined 또는 null 값에 대해 .map() 메서드를 호출하려고 할 때 발생하며, 애플리케이션의 렌더링을 완전히 중단시킬 수 있습니다. 이 글에서는 “Cannot read properties of undefined (reading ‘map’)” 에러의 근본 원인을 파악하고, 실전에서 바로 적용할 수 있는 해결 방법과 예방 전략을 상세히 알아보겠습니다.

2. 에러 상세 분석

이 에러 메시지는 JavaScript에서 undefined 또는 null 값을 가진 변수에 대해 속성이나 메서드에 접근하려고 할 때 발생합니다. React 컴포넌트에서는 주로 배열 데이터를 렌더링할 때 .map() 함수를 사용하는데, 이때 예상한 배열이 실제로는 undefined 상태인 경우 이 에러가 발생합니다.

에러가 발생하는 구체적인 시나리오는 다음과 같습니다:

• 타이밍 문제: 비동기 데이터가 아직 로드되지 않은 상태에서 렌더링을 시도할 때
• 데이터 구조 오해: API 응답 구조를 잘못 이해하여 존재하지 않는 속성에 접근할 때
• 초기화 누락: state나 props의 초기값을 설정하지 않았을 때
• 조건부 렌더링 부족: 데이터 존재 여부를 확인하지 않고 바로 map을 호출할 때

이 에러는 개발 환경뿐만 아니라 프로덕션 환경에서도 사용자 경험을 크게 저해할 수 있으므로, 적절한 에러 처리와 방어 코드를 작성하는 것이 매우 중요합니다.

3. 발생 원인 5가지

3.1 비동기 데이터 로딩 중 렌더링

가장 흔한 원인은 API에서 데이터를 가져오는 동안 컴포넌트가 렌더링되는 경우입니다. useEffect나 데이터 페칭 라이브러리를 사용할 때, 데이터가 아직 도착하지 않은 초기 렌더링 시점에 state는 undefined 상태입니다.

3.2 잘못된 초기값 설정

useState나 컴포넌트 props의 기본값을 설정하지 않거나, null 또는 undefined로 설정한 경우 map 메서드를 호출할 수 없습니다. React는 초기 렌더링 시 이러한 값으로 컴포넌트를 그리려고 시도하므로 에러가 발생합니다.

3.3 API 응답 구조 불일치

백엔드 API의 응답 구조가 예상과 다르거나 변경된 경우, 존재하지 않는 속성 경로에 접근하게 되어 undefined를 반환받습니다. 예를 들어 data.items를 기대했지만 실제로는 data.results에 배열이 있는 경우입니다.

3.4 조건부 렌더링 미적용

데이터의 존재 여부를 확인하는 조건문 없이 바로 map 함수를 호출하면, 데이터가 없는 상황에서 에러가 발생합니다. 특히 옵셔널 체이닝이나 논리 연산자를 사용하지 않은 경우 문제가 됩니다.

3.5 Props 전달 오류

부모 컴포넌트에서 자식 컴포넌트로 배열 데이터를 전달할 때, props가 제대로 전달되지 않거나 이름이 일치하지 않는 경우 자식 컴포넌트에서는 undefined를 받게 됩니다. 또한 구조 분해 할당 시 속성명 오타도 원인이 될 수 있습니다.

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

4.1 초기값을 빈 배열로 설정

가장 간단하고 효과적인 방법은 state의 초기값을 빈 배열로 설정하는 것입니다.

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

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

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

  return (
    

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

4.2 조건부 렌더링 적용

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

function ProductList({ products }) {
  return (
    

      {products && products.length > 0 ? (
        products.map(product => (
          
{product.name}
        ))
      ) : (
        
제품이 없습니다.
      )}
    
  );
}

4.3 옵셔널 체이닝과 Nullish Coalescing 사용

ES2020의 옵셔널 체이닝(?.)과 널 병합 연산자(??)를 활용하면 안전하게 데이터에 접근할 수 있습니다.

function CommentList({ post }) {
  return (
    

      {(post?.comments ?? []).map(comment => (
        
{comment.text}
      ))}
    
  );
}

4.4 로딩 상태 관리

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

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

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

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

  return (
    

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

4.5 Array.isArray() 검증

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

function ItemList({ items }) {
  return (
    

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

4.6 기본 Props 설정

컴포넌트의 defaultProps를 사용하여 props가 전달되지 않을 때의 기본값을 설정합니다.

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

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

// 또는 클래스 컴포넌트에서
class TaskList extends React.Component {
  static defaultProps = {
    tasks: []
  };

  render() {
    return (
      

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

4.7 에러 바운더리 구현

예상치 못한 에러를 포착하여 애플리케이션 전체가 중단되는 것을 방지합니다.

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

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

  componentDidCatch(error, errorInfo) {
    console.error('에러 발생:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return 
문제가 발생했습니다. 잠시 후 다시 시도해주세요.
;
    }

    return this.props.children;
  }
}

// 사용 예시
function App() {
  return (
    
      
  );
}

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

TypeScript 사용

TypeScript를 도입하면 컴파일 시점에 타입 불일치를 발견할 수 있어 런타임 에러를 크게 줄일 수 있습니다. 인터페이스와 타입 정의를 통해 데이터 구조를 명확히 하고, optional 속성 표시로 undefined 가능성을 명시할 수 있습니다.

항상 초기값 설정

모든 state와 변수에 적절한 초기값을 설정하는 습관을 들이세요. 배열은 빈 배열([])로, 객체는 빈 객체({})로 초기화하면 많은 에러를 예방할 수 있습니다.

방어적 프로그래밍

데이터를 사용하기 전에 항상 존재 여부를 확인하세요. 옵셔널 체이닝, 논리 연산자, 조건부 렌더링을 적극 활용하여 안전한 코드를 작성하세요.

API 응답 검증

백엔드 API 응답을 받은 후 데이터 구조를 콘솔로 확인하고, 예상한 형태인지 검증하세요. Zod나 Yup 같은 스키마 검증 라이브러리를 사용하면 더욱 안전합니다.

린팅 도구 활용

ESLint와 같은 린팅 도구를 설정하여 잠재적인 문제를 코드 작성 단계에서 발견하세요. react/prop-types, react/require-default-props 같은 규칙이 도움이 됩니다.

6. 마무리

“Cannot read properties of undefined (reading ‘map’)” 에러는 React 개발에서 매우 흔하지만, 올바른 이해와 적절한 방어 코드를 통해 충분히 예방하고 해결할 수 있습니다. 이 글에서 소개한 7가지 해결 방법을 상황에 맞게 적용하고, 베스트 프랙티스를 따른다면 더 안정적인 React 애플리케이션을 개발할 수 있을 것입니다. 초기값 설정, 조건부 렌더링, 타입 검증을 습관화하여 견고한 코드를 작성하시기 바랍니다. 에러는 학습의 기회이며, 이를 통해 더 나은 개발자로 성장할 수 있습니다.