Cannot convert undefined or null to object — 원인·해결·예방

Cannot convert undefined or null to object — 원인·해결·예방

자바스크립트에서 "TypeError: Cannot convert undefined or null to object"이 뜨면, 객체를 기대하는 자리에 undefined나 null을 넘겼다는 뜻이다. 대표적으로 Object.keys(x)·Object.values(x)·Object.entries(x)·Object.assign(x, ...) 같은 메서드는 인자로 객체가 와야 하는데, 그 자리에 undefined나 null이 오면 "이건 객체로 바꿀 수 없다"며 막힌다. 가장 흔한 상황이 API 데이터가 아직 안 왔는데 Object.keys(data)로 순회하려 할 때다. 처음 렌더링 시점엔 data가 undefined라 터진다. 이 글은 이 에러의 의미, 어떤 상황에서 나는지, 그리고 기본값과 빈 객체 보장으로 막는 해결법을 정리한다.

Cannot convert undefined or null to object

 

이 글의 구성

 

🔎에러 메시지의 의미

🧩자주 나오는 발생 원인 4가지

⚖️터지는 메서드 vs 안 터지는 것

💻재현과 진단

🛠해결 — 빈 객체 보장

💬자주 묻는 질문 5가지

---

🔎 에러 메시지의 의미

이 에러는 TypeError로, 객체가 필요한 자리에 undefined나 null을 넘겼을 때 발생한다. 자바스크립트의 여러 Object 정적 메서드는 인자를 객체로 다루려 하는데, undefined와 null은 객체로 변환할 수 없는 특수한 값이다. 그래서 Object.keys(undefined)처럼 부르면 "undefined나 null은 객체로 못 바꾼다"며 즉시 막힌다.

 

이 에러를 던지는 대표 메서드는 Object.keys·Object.values·Object.entries다. 셋 다 객체의 키나 값을 배열로 뽑아 주는 함수라, 대상이 진짜 객체여야 한다. 그밖에 Object.assign의 대상(첫 인자)이 null이거나, Object.getOwnPropertyNames·getPrototypeOf에 null·undefined를 넘겨도 같은 에러가 난다. 핵심은 "넘긴 값이 사실 객체가 아니었다"는 것이고, 대개 그 값이 아직 안 온 데이터라 undefined인 경우다.

핵심 — 객체 자리에 undefined·null이 왔다

Object.keys 같은 메서드는 "객체를 달라"고 요구하는데, undefined나 null은 객체로 바꿀 수 없어 막힌다. 그래서 디버깅의 첫걸음은 그 메서드에 넘긴 값이 정말 객체인지 console.log로 확인하는 것이다. undefined면 왜 비었는지(비동기·오타·미반환)를 추적한다.

---

🧩 자주 나오는 발생 원인 4가지

원인 1 — API 데이터가 오기 전 Object 메서드 호출

가장 흔하다. 응답이 도착하기 전 첫 렌더링에서 Object.keys(data)를 부른 경우다. 그 시점엔 data가 undefined라 터진다. React 같은 프레임워크에서 특히 잦다.

원인 2 — 함수가 값을 반환하지 않음·경로 오타

return을 빠뜨린 함수 결과나, res.data를 res.datas로 잘못 접근해 undefined가 된 값을 Object.entries에 넘긴 경우다. 중간 경로가 비면 그 결과도 undefined다.

원인 3 — Object.assign의 대상이 null

Object.assign(target, source)에서 target 자리에 null·undefined를 넘긴 경우다. 대상은 실제 객체여야 병합할 수 있다. 참고로 소스(뒤 인자)가 null·undefined면 그냥 무시되고 에러는 안 난다.

원인 4 — null로 초기화한 값을 그대로 순회

상태나 변수를 null로 초기화해 두고 값을 채우기 전에 Object.keys로 순회한 경우다. 명시적 null도 undefined와 마찬가지로 객체로 변환할 수 없어 막힌다.

---

⚖️ 터지는 메서드 vs 안 터지는 것

같은 undefined·null이라도 어디에 넘기느냐에 따라 터지기도 하고 조용히 넘어가기도 한다. 이 경계를 알면 헷갈림이 준다.

동작	null·undefined일 때
Object.keys·values·entries(x)	✗ 이 에러 발생
Object.assign(x, ...) 대상	✗ 이 에러 발생
for...in (x)	✓ 에러 없이 0번 순회
객체 전개 {...x}	✓ 에러 없이 무시

Object.keys 계열과 Object.assign의 대상은 객체를 강하게 요구해 null·undefined에서 터진다. 반면 for...in은 null·undefined를 순회하면 그냥 한 번도 돌지 않고 넘어가고, 객체 전개({...null})도 nullish를 무시해 에러가 없다. 한 가지 더, 객체 구조 분해(const { a } = null)는 터지지만 메시지가 다르다. 크롬·Node는 "Cannot destructure property 'a' of 'null' as it is null"처럼 별도 문구로 나온다(파이어폭스 등은 표현이 조금 다르다). 그래서 "Cannot convert ... to object"이면 Object 메서드 쪽을, 구조 분해 문구면 분해 대상을 본다.

---

💻 재현과 진단

전형적인 재현이다. undefined를 Object.keys에 넘기면 즉시 터진다.

// data가 아직 안 온 상태에서 순회
let data; // undefined
const keys = Object.keys(data);
// ✗ TypeError: Cannot convert undefined or null to object

// 넘긴 값부터 확인
console.log(data); // undefined ← 범인

진단은 Object 메서드에 넘긴 값의 정체를 확인하는 것이다. console.log로 그 값을 찍어 undefined·null인지 보고, 그렇다면 왜 비었는지(비동기 미도착·오타·미반환)를 거슬러 올라간다. 스택 추적에서 Object.keys 등이 호출된 줄을 찾으면 어느 값이 문제인지 좁혀진다.

// ✓ null 로 초기화한 값도 같은 에러
const config = null;
Object.entries(config);
// ✗ Cannot convert undefined or null to object

---

🛠 해결 — 빈 객체 보장

핵심은 Object 메서드에 넘기기 전에 값이 객체임을 보장하는 것이다. undefined·null일 수 있으면 기본값으로 빈 객체를 씌운다.

// ✓ 널 병합으로 빈 객체 보장
const keys = Object.keys(data ?? {});
// data가 없으면 빈 객체 → 빈 배열 반환, 에러 X

// ✓ 존재 확인 후 순회
if (data) {
  for (const [k, v] of Object.entries(data)) { ... }
}

상황별로 정리하면 이렇다. 대부분 기본값 하나로 깔끔하게 풀린다.

상황별 해결 방법

01빈 객체 보장 → Object.keys(x ?? {})·(x || {})로 감싸 순회.

02로딩 가드 → 데이터 도착 전엔 순회하지 않고 로딩 UI를 먼저.

03초기값 → 상태·변수를 null이 아니라 빈 객체({})로 초기화.

04Object.assign → 대상은 {} 같은 실제 객체로, null 대상 금지.

05근본 점검 → 그 값이 왜 undefined·null인지(비동기·오타) 고친다.

가장 간단한 예방은 상태나 변수의 초기값을 null 대신 빈 객체·빈 배열로 두는 것이다. 그러면 데이터가 오기 전에 Object.keys를 불러도 빈 결과가 나올 뿐 에러가 안 난다. 다만 기본값으로 에러만 막고 끝내지는 말자. 화면에 데이터가 계속 안 뜬다면, 정작 값이 왜 비었는지(응답 실패·경로 오타)라는 근본 원인은 그대로다.

---

💬 자주 묻는 질문 5가지

Q1Object.keys에서 자꾸 나요.

넘긴 값이 undefined·null일 때 납니다. API 데이터가 오기 전 첫 렌더링이 대표적이죠. Object.keys(data ?? {})처럼 빈 객체를 기본값으로 씌우면 에러 없이 빈 배열이 나옵니다. 초기 상태를 빈 객체로 두는 것도 방법입니다.

Q2for...in은 되는데 Object.keys는 안 돼요.

동작이 다르기 때문입니다. for...in은 null·undefined를 순회해도 그냥 0번 돌고 끝나지만, Object.keys 계열은 인자를 객체로 변환하려 해서 null·undefined에 터집니다. 안전하게 하려면 Object.keys에도 빈 객체 기본값을 씌우세요.

Q3?? {}랑 || {}는 뭐가 다른가요?

|| {}는 undefined·null뿐 아니라 0·빈 문자열·false 같은 falsy 값도 빈 객체로 대체합니다. ?? {}는 오직 undefined·null일 때만 대체하죠. 다만 이 에러는 대상이 객체여야 하는 자리라, 대개 어느 쪽을 써도 됩니다. 값 0을 살려야 하는 다른 맥락에선 ??가 안전합니다.

Q4구조 분해에서 나는 에러랑 같은 건가요?

비슷하지만 메시지가 다릅니다. const { a } = null처럼 null·undefined를 구조 분해하면 "Cannot destructure property ... of null"이라는 별도 문구가 납니다. "Cannot convert ... to object"은 Object.keys 같은 메서드 쪽이죠. 둘 다 "없는 값에서 객체를 기대했다"는 점은 같습니다.

Q5Object.assign에서 나요.

대상(첫 인자)이 null·undefined일 때 납니다. Object.assign(target, source)의 target은 실제 객체여야 병합됩니다. target을 {}로 두세요. 참고로 소스(뒤 인자)가 null·undefined인 건 그냥 무시되므로 에러가 안 납니다.

---

📌 결론

"Cannot convert undefined or null to object"은 Object.keys·values·entries·assign 같은 메서드에 객체 대신 undefined·null을 넘겼을 때 나는 TypeError다. 대개 데이터가 아직 안 와서 undefined인 값을 순회하려다 생긴다. 그래서 넘긴 값이 정말 객체인지부터 확인하는 게 출발점이다.

 

실무 원칙은 다음과 같다.

🔑 넘긴 값을 확인한다. Object 메서드에 넘긴 값을 console.log로 찍어 undefined·null인지 보고, 그렇다면 왜 비었는지 추적한다.

🛡 빈 객체를 보장한다. undefined·null 가능성엔 Object.keys(x ?? {})로 감싸거나, 존재 확인 후 순회한다.

📦 초기값을 챙긴다. 상태·변수를 null 대신 빈 객체·빈 배열로 초기화하면 데이터 도착 전에도 안전하다. 단, 값이 비는 근본 원인도 함께 고친다.

convert to object 에러 체크리스트

 

01Object 메서드에 넘긴 값을 console.log로 정체 확인.

02undefined·null이면 비동기·오타·미반환 원인 추적.

03Object.keys(x ?? {})로 빈 객체 기본값 보장.

04데이터 도착 전엔 로딩 가드로 순회 자체를 미룸.

05상태·변수 초기값을 null 대신 빈 객체·배열로.

06Object.assign 대상은 {} 등 실제 객체로.

---

본 글은 자바스크립트 TypeError(convert to object)의 일반적 원인과 해결 방법을 정리한 자료다. 코드 수정은 영향 범위를 확인한 뒤 신중히 적용한다.

 

#JavaScript #TypeError #Cannotconvert #undefined #null #자바스크립트에러 #Objectkeys #Objectentries #Objectassign #널병합 #빈객체 #API #프론트엔드 #JS디버깅 #웹개발