Blog

JavaScript TypeError: Cannot set property of null 에러란?

JavaScript 개발 중 TypeError: Cannot set property of null 에러를 만나면 당황스러울 수 있습니다. 이 에러는 null 값을 가진 객체에 속성을 설정하려고 할 때 발생하는 매우 흔한 런타임 에러입니다. DOM 조작, API 응답 처리, 객체 초기화 과정에서 자주 발생하며, 특히 초보 개발자들이 많이 겪는 문제입니다. 이 글에서는 TypeError: Cannot set property of null 에러의 원인을 명확히 파악하고, 실전에서 바로 적용할 수 있는 해결 방법을 코드 예제와 함께 상세히 설명하겠습니다. 이 가이드를 통해 에러를 신속하게 해결하고 재발을 방지하는 방법까지 익힐 수 있습니다.

에러 상세 분석

이 에러는 JavaScript의 엄격한 타입 체크 결과로 발생합니다. null은 ‘값이 없음’을 명시적으로 나타내는 특수한 값으로, 객체가 아니기 때문에 속성을 추가하거나 수정할 수 없습니다. 에러 메시지는 브라우저마다 약간씩 다르게 표시되는데, Chrome에서는 “Cannot set properties of null (setting ‘property’)”로, Firefox에서는 “TypeError: can’t set property on null”로 나타납니다. 이 에러는 컴파일 타임이 아닌 런타임에 발생하므로, 코드 실행 중에만 발견됩니다. 따라서 철저한 null 체크와 방어적 프로그래밍이 필수적입니다. 특히 DOM 요소를 다룰 때나 외부 데이터를 처리할 때 이 에러가 빈번하게 발생하며, 적절한 에러 핸들링이 없으면 애플리케이션 전체가 중단될 수 있습니다.

발생 원인 5가지

1. 존재하지 않는 DOM 요소 접근

가장 흔한 원인은 DOM에서 요소를 찾지 못한 경우입니다. document.getElementById()나 querySelector()가 요소를 찾지 못하면 null을 반환하는데, 이 null 값에 속성을 설정하려고 하면 에러가 발생합니다. HTML이 완전히 로드되기 전에 스크립트가 실행되거나, 잘못된 선택자를 사용한 경우에 이런 상황이 발생합니다.

2. 잘못된 API 응답 처리

서버에서 받은 데이터가 예상과 다를 때 발생합니다. API가 특정 객체를 반환할 것으로 예상했지만 null이나 undefined를 반환하는 경우, 해당 값의 속성에 접근하려고 하면 에러가 발생합니다. 네트워크 오류나 잘못된 요청으로 인해 빈 응답을 받을 때 특히 주의해야 합니다.

3. 초기화되지 않은 변수 사용

객체를 선언만 하고 초기화하지 않은 상태에서 속성을 설정하려고 할 때 발생합니다. let obj; obj.name = ‘test’; 같은 코드에서 obj는 undefined 상태이므로 에러가 발생합니다.

4. 타이밍 문제

비동기 작업에서 데이터가 아직 로드되지 않았는데 접근하려고 할 때 발생합니다. Promise나 async/await을 사용할 때 데이터가 준비되기 전에 속성에 접근하면 null 참조 에러가 발생할 수 있습니다.

5. 메모리에서 제거된 객체 접근

이미 메모리에서 제거되었거나 명시적으로 null로 설정된 객체에 접근할 때 발생합니다. 특히 이벤트 리스너나 콜백 함수에서 이미 제거된 DOM 요소를 참조하려고 할 때 이런 문제가 발생합니다.

해결방법 7가지

방법 1: null 체크로 조건부 실행

가장 기본적인 방법은 속성을 설정하기 전에 null 체크를 하는 것입니다.

const element = document.getElementById('myElement');
if (element !== null) {
  element.textContent = '새로운 텍스트';
  element.style.color = 'blue';
} else {
  console.error('요소를 찾을 수 없습니다.');
}

방법 2: Optional Chaining 사용

ES2020에서 도입된 Optional Chaining(?.)을 사용하면 간결하게 null 체크를 할 수 있습니다.

const user = getUserData();
user?.profile?.name = '홍길동'; // user나 profile이 null이면 에러 없이 undefined 반환

// DOM 조작에도 활용
const element = document.querySelector('.my-class');
element?.classList.add('active');

방법 3: DOMContentLoaded 이벤트 활용

DOM이 완전히 로드된 후에 스크립트를 실행하여 null 참조를 방지합니다.

document.addEventListener('DOMContentLoaded', function() {
  const element = document.getElementById('myElement');
  if (element) {
    element.innerHTML = '콘텐츠 로드 완료';
  }
});

// 또는 defer 속성 사용
// <script src="app.js" defer></script>

방법 4: Nullish Coalescing 연산자 사용

기본값을 제공하여 null이나 undefined를 안전하게 처리합니다.

const config = getConfig();
const settings = config ?? { theme: 'light', lang: 'ko' };
settings.theme = 'dark'; // config가 null이어도 안전

// 또는
const element = document.getElementById('header') ?? document.createElement('div');
element.className = 'header';

방법 5: try-catch 블록으로 에러 핸들링

에러가 발생할 가능성이 있는 코드를 try-catch로 감싸서 안전하게 처리합니다.

try {
  const data = JSON.parse(response);
  data.items.forEach(item => {
    item.processed = true;
  });
} catch (error) {
  console.error('데이터 처리 중 오류:', error);
  // 대체 로직 실행
  handleError(error);
}

방법 6: 타입 가드 함수 생성

재사용 가능한 검증 함수를 만들어 코드의 안정성을 높입니다.

function isValidElement(element) {
  return element !== null && element !== undefined && element instanceof HTMLElement;
}

const button = document.querySelector('.btn');
if (isValidElement(button)) {
  button.addEventListener('click', handleClick);
}

// 객체 검증
function hasProperty(obj, prop) {
  return obj !== null && obj !== undefined && prop in obj;
}

const user = getUser();
if (hasProperty(user, 'email')) {
  user.email = '[email protected]';
}

방법 7: 방어적 프로그래밍 패턴

초기값을 명확히 설정하고 항상 유효한 객체를 유지합니다.

// 객체 초기화를 명확히
let userData = {
  name: '',
  email: '',
  preferences: {}
};

// API 호출 후 안전하게 업데이트
async function updateUser() {
  const response = await fetch('/api/user');
  const data = await response.json();
  
  if (data && typeof data === 'object') {
    userData = { ...userData, ...data };
  }
}

// 기본값이 있는 팩토리 함수
function createUser(options = {}) {
  return {
    name: options.name || 'Guest',
    email: options.email || '',
    role: options.role || 'user'
  };
}

예방법과 베스트 프랙티스

TypeError: Cannot set property of null 에러를 예방하려면 몇 가지 모범 사례를 따라야 합니다. 첫째, TypeScript를 사용하여 컴파일 시점에 null 체크를 강제하는 것이 효과적입니다. strictNullChecks 옵션을 활성화하면 null 가능성이 있는 값을 사전에 감지할 수 있습니다. 둘째, ESLint 같은 린터를 설정하여 잠재적인 null 참조를 코드 작성 단계에서 발견합니다. 셋째, 모든 DOM 조작 전에 요소의 존재를 확인하는 습관을 들입니다. 넷째, API 응답에는 항상 유효성 검사를 수행하고 스키마 검증 라이브러리(Zod, Yup 등)를 활용합니다. 다섯째, 단위 테스트를 작성하여 null 케이스를 포함한 다양한 시나리오를 검증합니다. 여섯째, 코드 리뷰 과정에서 null 안전성을 중점적으로 검토합니다.

마무리

TypeError: Cannot set property of null 에러는 JavaScript 개발에서 매우 흔하게 발생하지만, 원인을 정확히 이해하고 적절한 해결 방법을 적용하면 쉽게 극복할 수 있습니다. null 체크, Optional Chaining, 방어적 프로그래밍 등의 기법을 일상적으로 사용하면 더 안정적이고 견고한 코드를 작성할 수 있습니다. 이 가이드에서 소개한 7가지 해결 방법을 프로젝트에 적용하여 에러 없는 개발 환경을 만들어보세요. 지속적인 학습과 실습을 통해 null 참조 에러를 완벽하게 예방하고, 더 나은 개발자로 성장할 수 있습니다.