TypeError: Cannot read properties of undefined 해결 — 원인과 안전한 패턴

증상: Cannot read properties of undefined

자바스크립트에서 가장 자주 만나는 에러 중 하나입니다.

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

구버전(또는 다른 엔진)에서는 Cannot read property 'name' of undefined로 나오기도 합니다. 메시지는 달라 보여도 원인은 같습니다. 괄호 안의 'name'이 핵심 단서입니다. "undefined인 무언가에서 name을 읽으려 했다"는 뜻이죠. 즉 obj.name에서 obj가 undefined였습니다. 여기서 흔히 하는 착각이 "name이 문제"라고 보는 것인데, 진짜 범인은 name 앞에 있는 객체입니다. 그 객체가 왜 undefined인지를 추적해야 합니다.

왜 이 TypeError가 나는가

흔한 원인 5가지

• 비동기 데이터가 아직 안 옴 — API 응답 전에 data.user.name을 렌더링. React에서 가장 흔합니다.
• 객체에 없는 중첩 속성 접근 — res.body.items[0].id인데 items가 비어 있음.
• 함수가 값을 return 안 함 — 반환값을 받아 속성 접근하면 undefined.
• 잘못된 import / 구조 분해 — import { foo }인데 실제로는 default export.
• 오타와 대소문자 — userName을 username으로.

케이스별 해결

1) 옵셔널 체이닝(?.)으로 안전하게 접근

중간 값이 없으면 에러 대신 undefined를 반환합니다.

// 위험
const name = user.profile.name;
// 안전
const name = user?.profile?.name;

2) 기본값 / null 병합(??)

const name = user?.name ?? '이름 없음';
const items = res.data?.items ?? [];

3) React: 로딩 가드와 초기 상태

React에서 이 에러의 90%는 "API 응답이 오기 전에 렌더링이 한 번 일어나기 때문"입니다. 첫 렌더 시점에는 상태가 비어 있으므로, 데이터가 오기 전 렌더링을 막아야 합니다.

const [data, setData] = useState(null); // 초기값 null
useEffect(() => { fetch('/api/me').then(r=>r.json()).then(setData); }, []);

if (!data) return <p>로딩 중...</p>;  // 가드
return <h1>{data.user.name}</h1>;

배열을 다루는 컴포넌트라면 초기값을 null이 아니라 []로 두는 것도 좋은 습관입니다. list.map(...)이 빈 배열에서는 안전하게 동작하기 때문입니다.

4) 배열은 길이와 인덱스를 확인

arr[0]은 빈 배열이면 undefined이고, 거기서 속성을 읽으면 바로 이 에러가 납니다.

const first = list.length > 0 ? list[0].id : null;
// 또는
const first = list[0]?.id ?? null;

5) 구조 분해 시 기본값

props나 함수 인자를 구조 분해할 때, 객체 자체가 undefined로 들어오면 분해 단계에서 터집니다. 기본값을 주면 막을 수 있습니다.

function Profile({ user = {} }) {   // user가 없어도 빈 객체
  return <span>{user.name ?? '익명'}</span>;
}

6) 진짜 원인 추적

에러를 가리지 말고 어디서 undefined가 생겼는지 찾으세요. 브라우저 콘솔의 스택 트레이스를 클릭하면 정확한 파일과 줄로 이동합니다. 그 줄 바로 위에 console.log(user)를 찍어 어느 단계에서 값이 비는지 확인하는 것이 근본 해결입니다. 디버거의 중단점(breakpoint)을 걸어 변수 값을 직접 들여다보는 것도 빠른 방법입니다.

원인별 비교

예방

• 외부에서 온 데이터(API, props)는 항상 옵셔널 체이닝으로 접근.
• TypeScript를 쓰면 컴파일 단계에서 undefined 가능성을 잡아줍니다.
• 기본값을 적극 활용해 "값이 없을 때"를 항상 처리.
• 옵셔널 체이닝으로 에러는 막되, 왜 값이 비는지는 반드시 추적하세요. 가리기만 하면 빈 화면 버그로 이어집니다.

자주 묻는 질문

Q1. 옵셔널 체이닝만 붙이면 끝인가요?

에러는 사라지지만 데이터가 안 보이는 문제는 남습니다. ?.는 안전장치일 뿐, undefined가 생긴 근본 원인(비동기 타이밍, 잘못된 키 등)을 함께 고쳐야 합니다.

Q2. 'reading' 뒤의 이름이 매번 달라요.

괄호 안 이름이 바로 접근하려던 속성입니다. 그 속성을 가진 객체가 undefined라는 뜻이므로, 그 객체가 어디서 만들어지는지 거슬러 올라가세요.

Q3. null일 때도 같은 에러가 나나요?

메시지가 ...of null로 바뀝니다. 원인과 해결은 동일합니다. ?.와 ??는 null과 undefined를 모두 안전하게 처리합니다.