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

React 개발을 하다 보면 “Cannot read properties of undefined (reading ‘map’)” 에러를 자주 마주치게 됩니다. 이 에러는 주로 배열 데이터를 렌더링할 때 발생하며, 개발자들이 가장 많이 겪는 런타임 에러 중 하나입니다. 특히 API에서 데이터를 받아올 때나 상태 관리 중에 자주 발생하는데, undefined 또는 null인 값에 대해 map() 메서드를 호출하려고 할 때 나타납니다. 이 에러를 정확히 이해하고 해결하는 것은 안정적인 React 애플리케이션을 만드는 데 필수적입니다. 이 글에서는 에러의 원인부터 해결 방법, 그리고 예방법까지 완벽하게 알아보겠습니다.

에러 상세 분석

이 에러 메시지는 JavaScript가 undefined 값의 ‘map’ 속성에 접근하려고 시도했을 때 발생합니다. map()은 배열 메서드이기 때문에, 배열이 아닌 값(undefined, null, 문자열, 숫자 등)에 대해 호출하면 에러가 발생합니다.

React 컴포넌트에서 일반적으로 다음과 같은 상황에서 발생합니다:

function UserList({ users }) {
  return (
    

      {users.map(user => (  // users가 undefined일 때 에러 발생
        
{user.name}
      ))}
    
  );
}

이 코드에서 users props가 전달되지 않거나 undefined 상태일 때 “Cannot read properties of undefined (reading ‘map’)” 에러가 발생합니다. 브라우저 콘솔에서 정확한 에러 위치를 확인할 수 있으며, React DevTools를 사용하면 컴포넌트의 props 상태를 실시간으로 확인할 수 있습니다.

발생 원인 5가지

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

useState를 사용할 때 초기값을 설정하지 않으면 undefined가 됩니다:

const [items, setItems] = useState(); // undefined로 초기화
// items.map() 호출 시 에러 발생

2. API 응답 대기 중

비동기 데이터를 가져올 때, 데이터가 아직 도착하지 않은 상태에서 렌더링을 시도하는 경우:

const [data, setData] = useState();

useEffect(() => {
  fetchData().then(response => setData(response));
}, []);

// 첫 렌더링 시 data는 undefined

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

부모 컴포넌트에서 필수 props를 전달하지 않았을 때:

 // users prop 누락
// UserList 내부에서 users.map() 호출 시 에러

4. 잘못된 API 응답 구조

API 응답의 데이터 구조를 잘못 파악한 경우:

// 실제 응답: { data: { items: [...] } }
// 잘못된 접근: response.items (undefined)
setItems(response.items); // 올바른 접근: response.data.items

5. 조건부 렌더링 누락

데이터가 준비되기 전에 map()을 호출하는 경우입니다. 로딩 상태나 데이터 존재 여부를 확인하지 않고 바로 렌더링을 시도하면 에러가 발생합니다.

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

방법 1: 빈 배열로 초기화

가장 기본적이고 효과적인 방법입니다:

const [items, setItems] = useState([]); // 빈 배열로 초기화

return (
  

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

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

function ProductList({ products }) {
  return (
    

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

방법 3: 논리 연산자 활용

function CommentList({ comments }) {
  return (
    

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

방법 4: 기본값 설정 (Default Props)

function ItemList({ items = [] }) {
  return (
    

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

방법 5: 조건부 렌더링

function UserList({ users }) {
  if (!users || users.length === 0) {
    return 
데이터가 없습니다.
;
  }
  
  return (
    

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

방법 6: 로딩 상태 추가

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

  useEffect(() => {
    fetchData()
      .then(response => setData(response))
      .finally(() => setLoading(false));
  }, []);

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

  return (
    

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

방법 7: Array.isArray() 검증

function SafeList({ items }) {
  const safeItems = Array.isArray(items) ? items : [];
  
  return (
    

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

예방법과 베스트 프랙티스

에러를 사전에 방지하기 위한 베스트 프랙티스를 소개합니다:

1. TypeScript 사용: 타입을 명시하여 컴파일 시점에 에러를 잡을 수 있습니다.

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

interface Props {
  users: User[];
}

function UserList({ users }: Props) {
  // TypeScript가 users 타입을 보장
}

2. PropTypes 정의: JavaScript 환경에서 타입 체크가 필요할 때 사용합니다.

import PropTypes from 'prop-types';

UserList.propTypes = {
  users: PropTypes.array.isRequired
};

3. ESLint 규칙 활용: eslint-plugin-react를 사용하여 잠재적 에러를 사전에 감지합니다.

4. 에러 바운더리 구현: 예상치 못한 에러를 우아하게 처리합니다.

class ErrorBoundary extends React.Component {
  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’)” 에러는 React 개발에서 흔히 마주치는 에러이지만, 원인을 정확히 파악하고 적절한 해결 방법을 적용하면 쉽게 해결할 수 있습니다. 가장 중요한 것은 데이터의 초기 상태를 올바르게 설정하고, 렌더링 전에 데이터의 존재 여부를 확인하는 것입니다. 빈 배열로 초기화하거나, 옵셔널 체이닝을 사용하거나, 조건부 렌더링을 구현하는 등의 방법을 상황에 맞게 선택하세요. TypeScript와 PropTypes를 활용하면 개발 단계에서 이러한 에러를 사전에 방지할 수 있습니다. 이 가이드를 참고하여 더욱 안정적인 React 애플리케이션을 개발하시기 바랍니다.