Cannot read properties of null 에러 쉽게 해결하기
1. null 에러가 뜻하는 것
Cannot read properties of null 에러는 JavaScript에서 가장 자주 만나는 오류 중 하나입니다. 뜻은 단순합니다. 존재하지 않는 값(null)에서 무언가를 읽으려 했다는 의미입니다. 예를 들어 null.textContent, null.value, null.addEventListener 같은 코드가 실행되면 바로 이 에러가 발생합니다.
중요한 포인트는 "문법이 틀렸다"보다 "대상이 아직 없거나 잘못 찾았다"에 가깝다는 점입니다. 즉, 코드 구조 전체를 뜯어고칠 필요 없이 요소를 찾는 시점과 선택자를 점검하면 대부분 해결됩니다. 초보 단계에서는 이 원리만 이해해도 디버깅 속도가 크게 빨라집니다.
2. 가장 흔한 발생 원인
null 에러는 비슷한 상황에서 반복됩니다. 아래 원인부터 확인하면 문제를 빠르게 좁힐 수 있습니다.
| 원인 | 설명 | 해결 포인트 |
|---|---|---|
| 선택자 오타 | id/class 이름이 HTML과 JS에서 다름 | 문자 하나까지 정확히 일치시키기 |
| 실행 시점 문제 | DOM 생성 전 스크립트가 먼저 실행됨 | DOMContentLoaded 또는 script 위치 조정 |
| 조건부 렌더링 | 특정 조건에서만 요소가 생성됨 | 요소 존재 여부 체크 후 접근 |
| 동적 페이지 전환 | SPA 라우팅 후 기존 요소가 사라짐 | 화면 변경 시점에 다시 선택 및 바인딩 |
| 잘못된 부모 범위 | querySelector 범위를 좁게 잡아 못 찾음 | document 기준으로 먼저 검증 후 범위 최적화 |
3. 단계별 해결 방법
1) 에러 줄 번호부터 확인
콘솔에서 에러 메시지를 클릭하면 파일과 줄 번호로 이동할 수 있습니다. 해당 줄에서 어떤 변수에 null이 들어왔는지 먼저 확인하세요. 예를 들어 const btn = document.getElementById('saveBtn') 다음 줄에서 btn.addEventListener가 깨진다면, btn이 null이라는 뜻입니다.
2) 선택자 결과를 직접 출력
문제 변수 바로 아래에 console.log(btn)을 찍어 실제 값을 확인합니다. null이 찍히면 선택자 문제, HTMLElement가 찍히면 그다음 로직을 봐야 합니다. 이 간단한 확인만으로 원인을 절반 이상 제거할 수 있습니다.
3) DOM 준비 후 실행되게 만들기
스크립트를 head에서 바로 실행하면 HTML이 아직 완성되지 않아 null이 나오기 쉽습니다. script 태그에 defer를 붙이거나, document.addEventListener('DOMContentLoaded', ...) 내부에서 초기화 코드를 실행하면 안전합니다. 특히 처음 프로젝트 구조를 만들 때 이 원칙을 잡아두면 재발이 줄어듭니다.
4) 방어 코드 추가
실무에서는 요소가 없을 가능성을 고려해 방어 코드를 넣는 편이 좋습니다. 예를 들어 if (btn) { ... } 형태로 분기하면 페이지별 요소 차이로 인한 런타임 중단을 막을 수 있습니다. 단, 방어 코드만 넣고 원인을 덮어두기보다 왜 null인지도 함께 해결해야 유지보수가 편해집니다.
4. 예방을 위한 코딩 습관
첫째, id와 class 네이밍 규칙을 정하고 복붙 후 이름 변경 누락을 줄이세요. 둘째, 초기화 함수에서 필요한 요소를 한 번에 선택하고 null 체크를 통과한 뒤 이벤트를 연결하세요. 셋째, 콘솔 에러를 무시하지 말고 첫 에러 즉시 해결하는 습관을 들이세요.
AI에게 수정 요청 시에는 "null 에러가 나요" 한 줄보다 에러 전체 문구, 해당 파일의 관련 코드, 실행 조건을 함께 전달하세요. 이렇게 하면 원인 파악이 빨라지고 재시도 횟수도 줄어듭니다. 결국 핵심은 정확한 위치 파악 + 실행 시점 관리 + 존재 여부 확인입니다.
5. 자주 묻는 질문
Q1. optional chaining(?.)을 쓰면 다 해결되나요?
A. 에러를 잠시 피할 수는 있지만 근본 원인은 남습니다. 요소가 왜 null인지 원인을 함께 해결해야 정상 동작을 보장할 수 있습니다.
Q2. getElementById와 querySelector 중 뭐가 더 좋나요?
A. 단일 id를 찾을 때는 getElementById가 직관적이고 빠릅니다. 복합 선택이 필요하면 querySelector를 쓰되 선택자 오타를 특히 주의하세요.
Q3. null 체크를 어디까지 해야 하나요?
A. 사용자 입력, 조건부 렌더링, 페이지 전환처럼 값이 변할 수 있는 지점은 체크하는 것이 안전합니다. 항상 존재가 보장되는 요소는 과도한 중복 체크를 줄여도 됩니다.