React 오류 'Cannot read properties of undefined' 해결법 총정리
React 프로젝트를 진행하다 보면 가장 자주 마주치는 에러 중 하나가 바로 'Cannot read properties of undefined' 입니다. 이 오류는 주로 객체나 상태(state)의 값이 undefined 상태에서 특정 속성을 읽으려 할 때 발생하는데요, 초보 개발자뿐만 아니라 숙련된 개발자도 종종 실수로 만나게 됩니다.
📌 목차
1. 오류 원인 간단 요약
이 오류는 JavaScript에서 undefined 값에 대해 속성을 읽으려고 할 때 발생합니다. 예를 들어 다음과 같은 코드에서:
const user = undefined;
console.log(user.name); // ❌ Cannot read properties of undefined (reading 'name')위와 같이 user가 정의되지 않은 상태에서 .name을 읽으려고 하면 해당 오류가 발생해요. React에서는 주로 props, state, API 응답값 등이 예상보다 늦게 로딩되거나 누락될 때 자주 발생합니다.
2. 실무에서 자주 발생하는 사례
이 오류는 React 컴포넌트에서 비동기 데이터를 다룰 때 특히 자주 발생합니다. 다음은 실무에서 흔히 마주치는 예시입니다.
function UserProfile({ user }) {
return <div>사용자 이름: {user.name}</div>;
}이 코드는 user 객체가 항상 존재한다고 가정하고 작성되었지만, 실제로는 부모 컴포넌트에서 아직 데이터를 받아오지 못한 경우 undefined일 수 있어요. 이때 user.name을 렌더링하려 하면 오류가 발생합니다.
또 다른 사례로는 API 호출 이후 상태가 설정되기 전에 컴포넌트가 렌더링되는 경우입니다:
const [user, setUser] = useState();
useEffect(() => {
fetch('/api/user')
.then(res => res.json())
.then(data => setUser(data));
}, []);
return <div>{user.name}</div>; // ❌ 오류 발생 가능상태 초기값이 설정되지 않은 경우에도 이런 문제가 생깁니다. 예를 들어, useState({})가 아닌 useState() 또는 useState(undefined)로 상태를 초기화했다면 안전하게 접근하지 않으면 오류가 날 수 있어요.
3. 해결법 및 코드 예시
이러한 오류는 방지하는 방법만 잘 알면 충분히 피할 수 있습니다. 대표적인 해결책은 다음과 같아요:
- 옵셔널 체이닝 (Optional Chaining) 사용
- 조건부 렌더링을 통해 안전하게 데이터 접근
- 초기 상태값을 명확히 설정
아래는 옵셔널 체이닝을 활용한 안전한 예시입니다:
function UserProfile({ user }) {
return <div>사용자 이름: {user?.name}</div>;
}또는 조건부 렌더링을 통해 컴포넌트가 안전하게 동작하도록 할 수도 있습니다:
{user ? <div>사용자 이름: {user.name}</div> : <p>로딩 중...</p>}이처럼 데이터가 존재할 때만 접근하도록 코드를 구성하면 오류 발생을 효과적으로 방지할 수 있습니다.
4. 자주 하는 실수와 방지 팁
많은 개발자들이 다음과 같은 실수로 인해 해당 오류를 유발하곤 합니다:
- 초기값을 생략하고 useState()만 사용하는 경우
- API 호출 전 데이터를 사용하려는 조급함
- 중첩된 객체 접근 시 모든 단계의 존재 여부를 확인하지 않음
예를 들어 다음과 같이 중첩 객체를 다룰 때:
const post = {
user: {
profile: {
name: "Alice"
}
}
};
console.log(post.user.profile.name); // ✅ 정상
console.log(post.comment.user.profile.name); // ❌ 오류 발생post.comment가 존재하지 않기 때문에 오류가 발생하게 됩니다. 이런 경우엔 다음과 같은 접근법이 유용해요:
console.log(post.comment?.user?.profile?.name); // ✅ undefined 반환, 오류 없음방지 팁으로는 다음을 기억해두면 좋아요:
- 상태 초기값은 항상
null, 빈 객체{}, 또는 기본 구조로 설정하세요. - 옵셔널 체이닝은 넓게 사용하되, 지나치게 남용하면 로직의 흐름을 놓치게 될 수 있어요.
- 조건부 렌더링을 통해 React 컴포넌트가 안정적으로 동작하게 만드세요.
5. 결론 및 개발자 팁
React에서 'Cannot read properties of undefined' 오류는 초보자에게는 당황스러울 수 있지만, 발생 원인을 이해하고 예방 습관을 들인다면 쉽게 피할 수 있는 오류입니다.
코드를 작성할 때는 항상 "이 값이 정말 존재할까?"를 한 번 더 생각하고 작성하는 습관이 중요해요. 비동기 로직에서는 로딩 상태 확인, 기본값 지정, 옵셔널 체이닝 세 가지를 기억해두면 실수를 줄일 수 있습니다.
마지막으로, React 공식 문서나 ESLint 설정을 활용하면 이러한 오류를 미리 감지하고 방지하는 데 큰 도움이 됩니다. 안정적인 코드를 작성하는 습관은 실력 향상의 지름길이에요.
🏷️ 태그
React, 오류 해결, Cannot read properties of undefined, JavaScript, 프론트엔드 디버깅