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. 에러 상세 분석

이 에러 메시지를 분석해보면 다음과 같은 의미를 가집니다:

• Cannot read properties: 속성을 읽을 수 없다
• of undefined: undefined 값에서
• (reading ‘map’): map 속성을 읽으려고 시도했다

즉, 배열이어야 할 변수가 undefined 상태이며, 이 상태에서 map() 메서드를 호출하려고 했다는 뜻입니다. JavaScript에서 undefined는 값이 할당되지 않은 상태를 의미하므로, map과 같은 배열 메서드를 사용할 수 없습니다. 이 에러는 주로 컴포넌트 렌더링 시점과 데이터 로딩 시점 간의 시간차로 인해 발생합니다. React는 컴포넌트를 먼저 렌더링하고, 이후에 비동기로 데이터를 가져오기 때문에 초기 렌더링 시점에 데이터가 아직 준비되지 않은 경우가 많습니다. 브라우저 콘솔에서 이 에러를 확인하면 정확히 어느 파일의 몇 번째 줄에서 발생했는지 추적할 수 있어 디버깅에 도움이 됩니다.

3. 발생 원인 5가지

3.1 API 데이터 로딩 전 렌더링

가장 흔한 원인입니다. 컴포넌트가 마운트되자마자 렌더링되지만, API 호출은 비동기로 진행되기 때문에 초기 state 값이 undefined인 상태에서 map()을 호출하게 됩니다.

function UserList() {
  const [users, setUsers] = useState(); // undefined로 초기화
  
  useEffect(() => {
    fetch('/api/users')
      .then(res => res.json())
      .then(data => setUsers(data));
  }, []);
  
  // 초기 렌더링 시 users는 undefined
  return users.map(user => 
{user.name}
); // 에러 발생!
}

3.2 잘못된 state 초기값 설정

useState의 초기값을 설정하지 않거나 null로 설정한 경우 발생합니다.

3.3 Props 전달 실패

부모 컴포넌트에서 자식 컴포넌트로 배열 props를 전달할 때, 조건부 렌더링이나 타이밍 이슈로 인해 undefined가 전달될 수 있습니다.

3.4 API 응답 구조 불일치

예상한 데이터 구조와 실제 API 응답 구조가 다를 때 발생합니다. 예를 들어 data.users를 기대했지만 실제로는 data.items로 반환되는 경우입니다.

3.5 조건부 렌더링 누락

데이터가 로딩되기 전이나, 에러 상태, 빈 배열 상태 등을 처리하지 않고 바로 map()을 호출하는 경우입니다.

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

4.1 기본값으로 빈 배열 설정

가장 간단하고 효과적인 방법입니다. state 초기값을 빈 배열로 설정하면 Cannot read properties of undefined (reading ‘map’) 에러를 방지할 수 있습니다.

function UserList() {
  const [users, setUsers] = useState([]); // 빈 배열로 초기화
  
  useEffect(() => {
    fetch('/api/users')
      .then(res => res.json())
      .then(data => setUsers(data));
  }, []);
  
  return (
    

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

4.2 Optional Chaining 사용

?. 연산자를 사용하여 안전하게 접근합니다.

function ProductList({ data }) {
  return (
    

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

4.3 조건부 렌더링으로 체크

데이터가 존재할 때만 map()을 실행합니다.

function CommentList({ comments }) {
  if (!comments) {
    return 
Loading...
;
  }
  
  return (
    

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

4.4 논리 AND 연산자 활용

function ItemList({ items }) {
  return (
    

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

4.5 기본값 설정 (Nullish Coalescing)

function PostList({ posts }) {
  const postList = posts ?? [];
  
  return (
    

      {postList.map(post => (
        
{post.title}
      ))}
    
  );
}

4.6 Loading State 구현

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

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

// 사용

  

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

에러를 미리 방지하기 위한 베스트 프랙티스는 다음과 같습니다:

• 항상 state를 적절한 초기값으로 설정: 배열 데이터는 빈 배열 [], 객체는 빈 객체 {}로 초기화합니다.
• TypeScript 사용: 타입을 명시하여 컴파일 시점에 오류를 잡을 수 있습니다.
• PropTypes 또는 TypeScript로 타입 검증: props의 타입을 명확히 정의합니다.
• 데이터 구조 검증: API 응답을 받은 후 예상한 구조인지 확인합니다.
• 로딩 상태 관리: 항상 loading, error, success 상태를 구분하여 관리합니다.
• Array.isArray() 체크: map() 사용 전 실제로 배열인지 확인합니다.

function SafeList({ items }) {
  if (!Array.isArray(items)) {
    console.error('items is not an array:', items);
    return null;
  }
  
  return items.map(item => 
{item.name}
);
}

6. 마무리

Cannot read properties of undefined (reading ‘map’) 에러는 React 개발에서 매우 흔하지만, 적절한 방어 코드와 상태 관리로 충분히 예방할 수 있습니다. 가장 중요한 것은 데이터가 항상 존재한다고 가정하지 않고, undefined나 null 상태를 항상 고려하는 것입니다. 초기값 설정, 조건부 렌더링, Optional Chaining 등의 기법을 적절히 조합하면 안정적인 React 애플리케이션을 만들 수 있습니다. 이 가이드가 여러분의 개발 생산성을 높이는 데 도움이 되기를 바랍니다. 에러가 발생했을 때는 당황하지 말고, 데이터의 흐름을 추적하여 어느 시점에 undefined가 되는지 확인하면 쉽게 해결할 수 있습니다.