TypeError: Cannot set property of null 완벽 해결 가이드

1. 도입 – TypeError: Cannot set property of null이란?

JavaScript 개발을 하다 보면 TypeError: Cannot set property of null 에러를 자주 마주치게 됩니다. 이 에러는 null 값을 가진 객체의 속성에 값을 할당하려고 할 때 발생하는 대표적인 런타임 에러입니다. 특히 DOM 조작이나 데이터 처리 과정에서 빈번하게 발생하며, 초보 개발자뿐만 아니라 숙련된 개발자도 종종 겪는 문제입니다. 이 에러는 코드 실행을 중단시키기 때문에 사용자 경험에 직접적인 영향을 미칩니다. 이 글에서는 TypeError: Cannot set property of null 에러의 발생 원인부터 실질적인 해결 방법, 그리고 예방 전략까지 체계적으로 알아보겠습니다.

2. 에러 상세 분석

이 에러는 JavaScript 엔진이 null 값에 대해 속성 설정을 시도할 때 발생합니다. null은 “값이 없음”을 명시적으로 나타내는 특수한 값으로, 객체가 아니기 때문에 속성을 가질 수 없습니다. 에러 메시지의 전체 형태는 “TypeError: Cannot set property ‘propertyName’ of null”로 표시되며, 어떤 속성에 접근하려 했는지도 함께 알려줍니다.

이 에러는 주로 다음과 같은 상황에서 발생합니다:

• DOM 요소를 찾지 못한 경우 (document.querySelector가 null 반환)
• API 응답에서 예상한 객체가 없는 경우
• 초기화되지 않은 변수에 접근하는 경우
• 비동기 처리 중 타이밍 문제로 객체가 아직 생성되지 않은 경우

이 에러는 런타임에만 감지되므로, 코드 작성 시점에서는 발견하기 어렵습니다. 따라서 방어적 프로그래밍과 철저한 테스트가 필수적입니다.

3. 발생 원인 5가지

원인 1: DOM 요소를 찾지 못함

가장 흔한 원인으로, document.querySelector나 getElementById가 해당 요소를 찾지 못해 null을 반환하는 경우입니다. HTML이 완전히 로드되기 전에 스크립트가 실행되거나, 선택자가 잘못되었을 때 발생합니다.

// 잘못된 예시
const element = document.querySelector('.non-existent');
element.textContent = 'Hello'; // TypeError 발생

원인 2: API 응답 데이터 누락

서버에서 받은 데이터가 예상한 구조와 다르거나, 특정 속성이 없을 때 발생합니다. 네트워크 오류나 서버 측 문제로 인해 데이터가 제대로 전달되지 않은 경우가 많습니다.

// API 응답이 null인 경우
const response = await fetch('/api/user');
const data = await response.json();
data.user.name = 'John'; // data.user가 null이면 에러

원인 3: 변수 초기화 누락

객체를 선언만 하고 초기화하지 않아 null 상태로 남아있을 때 발생합니다. 조건부 초기화 로직에서 특정 조건이 충족되지 않을 때 자주 나타납니다.

let userConfig = null;
if (someCondition) {
    userConfig = { theme: 'dark' };
}
// someCondition이 false면 userConfig는 여전히 null
userConfig.theme = 'light'; // TypeError

원인 4: 비동기 타이밍 문제

비동기 작업이 완료되기 전에 결과에 접근하려 할 때 발생합니다. Promise나 콜백 처리가 제대로 되지 않은 경우 흔히 볼 수 있습니다.

원인 5: 중첩 객체 접근 오류

깊게 중첩된 객체 구조에서 중간 경로의 속성이 null이거나 undefined일 때 발생합니다. 옵셔널 체이닝 없이 접근하면 에러가 발생합니다.

4. 해결방법 7가지 (코드 포함)

해결법 1: null 체크 후 속성 설정

가장 기본적인 방법으로, 객체가 null이 아닌지 확인한 후 속성을 설정합니다.

const element = document.querySelector('.my-element');

if (element !== null) {
    element.textContent = 'Hello World';
} else {
    console.error('Element not found');
}

해결법 2: 옵셔널 체이닝 사용

ES2020에서 도입된 옵셔널 체이닝(?.)을 사용하면 안전하게 속성에 접근할 수 있습니다.

// 읽기에는 유용하지만, 설정에는 제한적
const value = obj?.property?.nested;

// 설정 전 체크
if (obj?.property) {
    obj.property.nested = 'value';
}

해결법 3: Nullish 병합 연산자 활용

기본값을 제공하여 null이나 undefined를 방지합니다.

let config = getUserConfig() ?? { theme: 'light', lang: 'ko' };
config.theme = 'dark'; // 안전하게 설정 가능

// DOM 요소에도 적용
const element = document.querySelector('.btn') ?? document.createElement('button');
element.className = 'btn-primary';

해결법 4: DOMContentLoaded 이벤트 활용

DOM이 완전히 로드된 후 스크립트를 실행하여 요소를 확실히 찾을 수 있게 합니다.

document.addEventListener('DOMContentLoaded', () => {
    const element = document.querySelector('.my-element');
    if (element) {
        element.textContent = 'Loaded!';
    }
});

// 또는 defer 속성 사용
// 

해결법 5: try-catch 블록으로 에러 처리

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

try {
    const data = JSON.parse(responseText);
    data.user.profile.avatar = 'new-avatar.jpg';
} catch (error) {
    console.error('데이터 설정 실패:', error.message);
    // 대체 로직 실행
    handleDataError();
}

해결법 6: 방어적 객체 초기화

객체를 사용하기 전에 항상 적절히 초기화합니다.

// 나쁜 예
let userSettings = null;

// 좋은 예
let userSettings = {
    theme: 'light',
    notifications: true,
    language: 'ko'
};

// 또는 조건부 초기화
let userSettings = loadSettings() || getDefaultSettings();
userSettings.theme = 'dark'; // 안전

해결법 7: 헬퍼 함수 작성

안전한 속성 설정을 위한 유틸리티 함수를 만듭니다.

function safeSetProperty(obj, prop, value) {
    if (obj !== null && obj !== undefined) {
        obj[prop] = value;
        return true;
    }
    console.warn(`Cannot set property ${prop} on null/undefined`);
    return false;
}

// 사용 예시
const element = document.querySelector('.target');
safeSetProperty(element, 'textContent', 'Safe Text');

// 중첩 객체용 헬퍼
function safeSet(obj, path, value) {
    const keys = path.split('.');
    let current = obj;
    
    for (let i = 0; i < keys.length - 1; i++) {
        if (current[keys[i]] === null || current[keys[i]] === undefined) {
            current[keys[i]] = {};
        }
        current = current[keys[i]];
    }
    
    current[keys[keys.length - 1]] = value;
}

safeSet(data, 'user.profile.name', 'John');

5. 예방법과 베스트 프랙티스

TypeScript 도입

TypeScript를 사용하면 컴파일 타임에 null 체크를 강제하여 많은 에러를 사전에 방지할 수 있습니다. strictNullChecks 옵션을 활성화하면 더욱 강력한 타입 안정성을 확보할 수 있습니다.

// TypeScript 예시
function setElementText(element: HTMLElement | null, text: string) {
    if (element === null) {
        throw new Error('Element is null');
    }
    element.textContent = text; // 안전
}

린터 규칙 설정

ESLint와 같은 린터를 사용하여 잠재적인 null 접근을 경고받을 수 있습니다. no-unsafe-optional-chaining, no-null 등의 규칙을 활성화하세요.

단위 테스트 작성

null이나 undefined가 전달되는 엣지 케이스를 테스트하여 에러를 조기에 발견합니다. Jest나 Mocha와 같은 테스트 프레임워크를 활용하세요.

일관된 초기화 패턴

프로젝트 전체에서 일관된 변수 초기화 패턴을 유지하고, null 대신 빈 객체나 배열을 기본값으로 사용하는 것을 고려하세요.

6. 마무리

TypeError: Cannot set property of null 에러는 JavaScript 개발에서 흔히 마주치는 문제지만, 올바른 이해와 대응 방법을 알면 충분히 예방하고 해결할 수 있습니다. 이 글에서 소개한 7가지 해결 방법과 베스트 프랙티스를 적용하면 더욱 안정적인 코드를 작성할 수 있습니다. 특히 null 체크, 옵셔널 체이닝, 방어적 프로그래밍을 습관화하면 이러한 에러를 크게 줄일 수 있습니다. 개발 과정에서 항상 "이 값이 null일 수 있는가?"를 고민하는 자세가 중요합니다. 안정적이고 견고한 JavaScript 애플리케이션을 만들어가시기 바랍니다.