Cannot read properties of undefined (reading 'x')를 만났을 때 확인 순서

문제 발생

목록 화면이 흰 화면으로 죽고 콘솔에 이 메시지가 찍혔습니다.

TypeError: Cannot read properties of undefined (reading 'name')

브라우저마다 문구가 다릅니다.

원인 분석

읽으려던 속성이 없다는 뜻이 아닙니다. 속성을 읽으려 한 대상 값 자체가 undefined나 null 이라는 뜻입니다. 메시지에는 읽으려던 속성 이름(name)만 나오므로, 정작 범인인 앞쪽 값은 직접 찾아야 합니다.

const user = users.find((u) => u.id === id);   // 못 찾으면 undefined
user.name;                                     // 여기서 터진다

값이 비는 경로는 대체로 정해져 있습니다.

• find/filter의 결과가 없을 때
• 배열의 범위를 넘는 인덱스
• API 응답에 기대한 필드가 없을 때(선택 필드, 오류 응답, 아직 로딩 중)
• 객체 구조 분해에서 중간 단계가 없을 때

해결 방안

1. 한 줄에 이어진 접근을 나눠 어느 단계가 비는지 확인합니다. 진단이 먼저입니다.

console.log({ user, address: user?.address });

2. 없을 수 있는 값은 옵셔널 체이닝으로 읽습니다. 값이 null/undefined면 오류 대신 undefined를 돌려줍니다.

const name = user?.name ?? "이름 없음";

??는 ||와 다릅니다 — 0이나 ""을 유효한 값으로 남겨 둡니다.

3. 옵셔널 체이닝으로 문제를 덮지 않습니다. "없으면 안 되는" 값이라면 ?.는 오류를 undefined로 바꿔 더 먼 곳에서 터지게 만들 뿐입니다. 그 경우에는 없다는 사실을 그 자리에서 처리합니다.

const user = users.find((u) => u.id === id);
if (!user) return <NotFound />;

4. 로딩 상태를 데이터 없음과 구분합니다. 프런트엔드에서 가장 흔한 원인입니다 — 아직 도착하지 않은 것과 없는 것은 다른 상태입니다.
5. 경계에서 응답 형태를 검증합니다. 서버가 준 JSON을 그대로 믿지 않고 스키마로 확인하면, 오류가 화면 깊은 곳이 아니라 경계에서 납니다. 이 저장소도 폼과 API 경계에서 Zod로 검증합니다.
6. TypeScript를 쓴다면 strictNullChecks를 켭니다. find의 반환 타입이 T | undefined가 되어 이 실수를 컴파일 타임에 잡습니다.

공식 문서

• MDN: TypeError — 예상치 못한 타입
• MDN: 옵셔널 체이닝 (?.)
• MDN: 널 병합 연산자 (??)