Cannot read properties of undefined 오류 해결법, 원인 10가지
자바스크립트로 개발하다가 콘솔에 Cannot read properties of undefined라는 빨간 오류가 나타나면 어디서부터 확인해야 할지 난감할 수 있습니다.
reading 'length', reading 'map', reading 'name'처럼 뒤에 특정 속성명이 붙어 나타나는 경우가 많은데요.
이 오류는 원리만 이해하면 의외로 해결하기 어렵지 않습니다.
Cannot read properties of undefined 오류 해결법과 실무에서 자주 만나는 원인 10가지를 예제와 함께 자세히 알아보겠습니다.
Cannot read properties of undefined란?
이 메시지는 자바스크립트의 TypeError 중 하나입니다. 쉽게 설명하면 값이 undefined인 상태인데 그 값에서 특정 속성(property)을 읽거나 메서드를 사용하려고 했다는 뜻입니다.
const user = undefined;
console.log(user.name);
// TypeError: Cannot read properties of undefined
// (reading 'name')
위 코드에서 user에는 객체가 아닌 undefined가 들어 있습니다. 그런데 바로 user.name에 접근했기 때문에 오류가 발생합니다.
MDN에서도 null과 undefined에는 접근할 수 있는 속성이 없기 때문에 이러한 동작에서 TypeError가 발생한다고 설명합니다.
Cannot read properties 오류, 가장 흔한 원인 10가지
1. 변수 값이 undefined인 경우
변수는 선언했지만 실제 객체가 할당되지 않은 상태에서 속성에 접근하는 가장 기본적인 사례입니다. 오류가 발생한 줄 바로 앞에서 console.log()로 값을 확인하면 빠르게 찾을 수 있습니다.
2. API 응답 구조를 잘못 예상한 경우
서버 응답이 data.user.name이라고 예상했지만 실제로는 data.result.user.name처럼 다른 구조일 수 있습니다. API를 사용할 때는 응답 데이터를 먼저 출력해 실제 JSON 구조를 확인하는 것이 좋습니다.
3. 비동기 데이터가 도착하기 전에 접근한 경우
fetch, Promise, async/await 등을 사용하는 코드에서는 데이터가 준비되기 전에 값을 읽으면서 오류가 발생하기 쉽습니다. 비동기 처리가 완료된 다음 해당 객체를 사용하는지 실행 순서를 확인해 보세요.
4. 배열에 없는 요소에 접근한 경우
존재하지 않는 배열 인덱스에 접근하면 결과가 undefined가 될 수 있습니다. 이후 해당 값의 속성을 다시 읽으면 Cannot read properties 오류로 이어집니다.
const users = [];
console.log(users[0]); // undefined
console.log(users[0].name); // TypeError
5. 중첩 객체의 일부 값이 없는 경우user.profile.address.city처럼 객체가 여러 단계로 연결되어 있다면 중간의 profile이나 address가 undefined일 수 있습니다. 깊은 객체일수록 어느 단계에서 값이 사라졌는지 하나씩 확인해야 합니다.
6. 함수 반환값이 undefined인 경우
함수에서 return을 빠뜨렸거나 특정 조건에서 아무 값도 반환하지 않았다면 호출 결과가 undefined가 될 수 있습니다. 반환된 값을 바로 객체처럼 사용하지 말고 실제 결과를 확인하는 습관이 필요합니다.
7. DOM 요소를 찾지 못한 경우
브라우저에서는 선택자에 맞는 DOM 요소가 없을 때 querySelector()가 null을 반환합니다. 이 경우 메시지는 undefined가 아니라 null과 관련된 TypeError로 나타날 수 있지만, 해결 원리는 비슷합니다. 선택자가 올바른지와 DOM 생성 시점을 함께 확인하세요.
8. 조건에 따라 값이 할당되지 않는 경우
if문 내부에서만 객체를 할당하도록 작성했다면 조건이 충족되지 않았을 때 예상했던 데이터가 만들어지지 않을 수 있습니다. 모든 실행 경로에서 필요한 값이 제대로 초기화되는지 살펴보는 것이 중요합니다.
9. 객체 초기값을 잘못 설정한 경우
React 등 프론트엔드 환경에서 초기 상태를 undefined로 지정한 뒤 렌더링 과정에서 바로 내부 속성을 읽으면 오류가 발생할 수 있습니다. 데이터 형태에 맞는 초기값을 지정하거나 값 존재 여부를 검사한 후 렌더링하는 방식으로 대응할 수 있습니다.
10. 외부 라이브러리·플러그인 사용 방식이 잘못된 경우
라이브러리가 아직 초기화되지 않았거나 예상한 객체를 제공하지 않는 상황에서도 같은 오류가 나타날 수 있습니다. 라이브러리 버전과 공식 API 사용법, 초기화 순서를 확인해 보세요.
undefined 오류 해결, Optional Chaining 활용하기
중첩 객체를 안전하게 확인할 때 유용한 기능이 Optional Chaining(?.)입니다. 객체 중간 값이 null 또는 undefined라면 오류를 발생시키는 대신 해당 체인의 평가를 중단하고 undefined를 반환합니다.
const name = user?.profile?.name;
예를 들어 user.profile.name을 바로 사용하는 대신 위처럼 작성하면 user 또는 profile이 없는 상황에 대응할 수 있습니다. 다만 ?.를 무조건 붙여 오류를 숨기기보다는 해당 값이 없어도 정상적인 상황인지 먼저 판단하는 것이 중요합니다.
Cannot read properties 해결에 기본값 설정하기
데이터가 없을 때 사용할 기본값이 명확하다면 Nullish Coalescing 연산자(??)와 Optional Chaining을 함께 활용할 수 있습니다. 특히 배열 데이터를 받을 때 유용합니다.
const items = response?.data?.items ?? [];
console.log(items.length);items가 null 또는 undefined라면 빈 배열을 사용하므로 이후 배열 처리 코드를 비교적 안전하게 작성할 수 있습니다. 문자열이라면 "", 객체라면 {}처럼 데이터 성격에 맞는 기본값을 선택하는 것이 핵심입니다.
TypeError를 빠르게 디버깅하는 순서
오류를 발견했다면 먼저 콘솔 메시지의 reading 'xxx' 부분을 확인하세요.
예를 들어 Cannot read properties of undefined (reading 'length')라면 .length 바로 왼쪽에 있는 값이 왜 undefined가 되었는지 추적해야 합니다.
그다음 오류가 발생한 파일과 줄 번호로 이동해 값을 console.log()로 출력합니다. 이후 API 응답 구조, 배열 인덱스, 함수 반환값, 비동기 실행 시점, 객체 초기값 순서로 점검하면 원인을 찾기 한결 쉬워집니다.
| 상황 | 확인할 내용 |
| 객체 속성 접근 | 부모 객체가 undefined인지 확인 |
| API 데이터 | 실제 응답 JSON 구조 확인 |
| 배열 접근 | 인덱스와 배열 길이 확인 |
| 비동기 처리 | 데이터 로딩 완료 시점 확인 |
| 중첩 객체 | Optional Chaining 적용 검토 |
| 함수 실행 | return 값 확인 |
Cannot read properties of undefined 예방 팁
가장 중요한 습관은 값이 존재한다고 무조건 가정하지 않는 것입니다. 외부 API 데이터나 사용자 입력처럼 형태가 달라질 가능성이 있는 데이터라면 사용 전에 검증하는 것이 좋습니다.
TypeScript를 사용해 데이터 타입을 명확히 정의하는 것도 실수를 줄이는 데 도움이 됩니다. ESLint와 같은 정적 분석 도구를 함께 사용하고 API 응답 타입까지 관리하면 런타임에 문제를 발견하는 상황을 줄일 수 있습니다.
Cannot read properties of undefined는 결국 undefined인 값에서 속성이나 메서드를 사용하려고 할 때 만나는 오류입니다.
변수 초기화, API 응답, 비동기 처리, 배열 인덱스, 중첩 객체부터 차례로 확인하고 필요한 경우 ?.와 ??를 적절하게 활용해 보세요. 원인이 되는 값을 찾는 습관만 익히면 훨씬 빠르게 해결할 수 있습니다.