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

도입

React 개발을 하다 보면 “Cannot read properties of undefined (reading ‘map’)” 에러를 자주 마주치게 됩니다. 이 에러는 특히 API에서 데이터를 받아와 리스트를 렌더링할 때 빈번하게 발생하는 대표적인 런타임 에러입니다. 초보 개발자뿐만 아니라 경험이 많은 개발자들도 종종 겪는 이 문제는, 배열이 undefined 상태일 때 map 메서드를 호출하려고 시도하면서 발생합니다. 이 글에서는 이 에러의 정확한 원인과 다양한 해결 방법, 그리고 미리 예방할 수 있는 베스트 프랙티스까지 상세하게 다루겠습니다.

에러 상세 분석

“Cannot read properties of undefined (reading ‘map’)” 에러는 JavaScript의 TypeError에 속하며, undefined 또는 null 값에 대해 속성이나 메서드에 접근하려고 할 때 발생합니다. React에서 이 에러가 특히 자주 발생하는 이유는 컴포넌트가 렌더링되는 시점과 데이터가 로드되는 시점 사이의 타이밍 차이 때문입니다.

React 컴포넌트는 초기 렌더링 시 state가 초기값으로 설정되어 있고, 비동기 데이터 페칭이 완료되기 전까지는 데이터가 undefined 상태입니다. 이때 JSX에서 배열에 대해 map()을 호출하면 에러가 발생합니다. 브라우저 콘솔에서 이 에러 메시지를 보면 정확히 어느 컴포넌트의 어느 라인에서 문제가 발생했는지 확인할 수 있으며, 스택 트레이스를 통해 호출 경로를 추적할 수 있습니다.

발생 원인 5가지

1. 초기 State 값 미설정

가장 흔한 원인은 useState의 초기값을 설정하지 않았거나 undefined로 설정한 경우입니다. React는 컴포넌트가 마운트되는 즉시 렌더링을 시도하므로, 이때 state가 undefined면 map 호출 시 에러가 발생합니다.

2. 비동기 데이터 로딩

API 호출이나 데이터베이스 조회와 같은 비동기 작업이 완료되기 전에 컴포넌트가 렌더링되면, 데이터가 아직 도착하지 않은 상태(undefined)에서 map을 호출하게 됩니다. useEffect 내에서 데이터를 가져오는 경우 특히 주의해야 합니다.

3. Props 전달 오류

부모 컴포넌트에서 자식 컴포넌트로 배열을 props로 전달할 때, 부모에서 해당 값이 undefined이거나 전달 자체가 누락되면 자식 컴포넌트에서 Cannot read properties of undefined (reading ‘map’) 에러가 발생합니다.

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

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

5. 조건부 렌더링 누락

데이터가 로드되지 않았을 때에 대한 처리 없이 바로 map을 사용하면 에러가 발생합니다. 로딩 상태나 데이터 존재 여부를 확인하는 조건부 렌더링이 필요합니다.

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

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

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

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

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

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

  return (
    

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

해결법 2: Optional Chaining과 기본값 사용

Optional chaining(?.)과 nullish coalescing(??)를 활용하여 안전하게 데이터에 접근합니다.

function ProductList({ data }) {
  const products = data?.products ?? [];

  return (
    

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

해결법 3: 조건부 렌더링 적용

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

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

  return (
    

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

해결법 4: 로딩 상태 관리

데이터 로딩 중임을 나타내는 별도의 state를 관리합니다.

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

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

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

  return (
    

      {articles.map(article => (
        

          
{article.title}
        
      ))}
    
  );
}

해결법 5: Array.isArray()로 타입 체크

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

function ItemList({ items }) {
  return (
    

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

해결법 6: Try-Catch로 에러 처리

에러 경계(Error Boundary)를 활용하여 런타임 에러를 포착합니다.

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

function App() {
  return (
    
      
  );
}

해결법 7: TypeScript로 타입 안전성 확보

TypeScript를 사용하여 컴파일 시점에 타입 오류를 잡아냅니다.

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

interface Props {
  users?: User[];
}

function UserList({ users = [] }: Props) {
  return (
    

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

예방법과 베스트 프랙티스

1. 항상 초기값 설정하기

useState를 사용할 때는 항상 적절한 초기값을 설정합니다. 배열의 경우 빈 배열([])을, 객체의 경우 빈 객체({})를 사용하세요.

2. PropTypes 또는 TypeScript 사용

컴포넌트의 props 타입을 명시적으로 정의하여 잘못된 데이터 전달을 방지합니다.

3. API 응답 구조 문서화

API 응답의 구조를 정확히 파악하고 문서화하여 팀원들과 공유합니다. Swagger나 Postman을 활용하면 효과적입니다.

4. 데이터 페칭 라이브러리 활용

React Query, SWR, Apollo Client 같은 라이브러리를 사용하면 로딩, 에러, 데이터 상태를 자동으로 관리해줍니다.

5. ESLint 규칙 설정

ESLint의 no-unsafe-optional-chaining, no-unsafe-member-access 같은 규칙을 활성화하여 잠재적 에러를 미리 감지합니다.

마무리

“Cannot read properties of undefined (reading ‘map’)” 에러는 React 개발에서 피할 수 없는 흔한 문제지만, 원인을 정확히 이해하고 적절한 방어 코드를 작성하면 충분히 예방할 수 있습니다. 초기 state 설정, 조건부 렌더링, 타입 체크 등의 기본적인 예방책을 습관화하면 더 안정적인 React 애플리케이션을 개발할 수 있습니다. 이 글에서 소개한 7가지 해결 방법을 프로젝트 상황에 맞게 적용해보시기 바랍니다.