jQuery 사용 시 발생하는 Cannot read properties of null 오류 해결 방법

jQuery로 DOM을 조작하다 보면 다음과 같은 오류가 자주 발생합니다.

 

Uncaught TypeError: Cannot read properties of null (reading 'addClass')

 

또는 상황에 따라 다음과 같은 형태로 나타나기도 합니다.

 

Cannot read properties of null (reading 'removeClass')
Cannot read properties of null (reading 'value')
Cannot read properties of null (reading 'style')

 

이 오류는 jQuery뿐 아니라 순수 JavaScript에서도 자주 발생하는 기본적인 DOM 참조 오류입니다.
핵심 원인은 선택자가 가리키는 요소가 존재하지 않는데 그 요소의 속성이나 메서드를 호출하려고 했기 때문입니다.

이 글에서는 이 오류가 발생하는 원리와 대표적인 원인, 그리고 해결 방법을 정리하겠습니다.

 

1. 오류의 의미

오류 메시지의 의미는 다음과 같습니다.

• Cannot read properties of null
  null 값의 속성을 읽을 수 없다
• reading 'addClass'
  addClass라는 기능을 null에서 호출하려고 했다

즉, 다음 코드에서처럼 선택자가 아무 요소도 찾지 못해 null을 반환한 상태에서 메서드를 실행한 것입니다.

document.getElementById('target').classList.add('active');

또는 jQuery의 경우 선택자 결과가 비어 있을 때 발생할 수 있습니다.

$('#target').addClass('active');

 

target이라는 id를 가진 요소가 존재하지 않으면 동일한 오류가 발생합니다.

 

2. 요소가 존재하지 않는 경우

<div id="box"></div>

<script>
  $('#notExist').addClass('on');
</script>

해결 방법
HTML 요소가 존재하는지 다시 확인하거나, 선택자 이름을 정확히 기재해야 합니다.

 

3. DOM이 완전히 로드되기 전에 스크립트가 먼저 실행된 경우

다음과 같은 코드를 보겠습니다.

<script>
  $('#menu').addClass('show');
</script>

<div id="menu"></div>

 

 

브라우저는 위에서 아래로 해석하기 때문에 스크립트가 실행되는 시점에는 아직 menu 요소가 생성되지 않은 상태일 수 있습니다.

 

해결 방법
jQuery의 ready 함수를 사용해 DOM이 준비된 이후에 실행되도록 합니다.

$(document).ready(function(){
  $('#menu').addClass('show');
});

또는

$(function(){ $('#menu').addClass('show'); });

을 사용할 수 있습니다.

 

 

4. 특정 화면에서만 요소가 존재하는 경우

실무에서 다음과 같은 상황이 자주 발생합니다.

• 특정 메뉴에서는 해당 요소가 보이지만
• 다른 메뉴에서는 요소가 렌더링되지 않는 구조

예시

$('#alertBox').text('완료되었습니다.');

alertBox가 로그인 화면에는 있지만 회원가입 화면에는 없을 때 특정 페이지에서만 오류가 발생합니다.

해결 방법
요소가 존재할 때만 실행하도록 조건을 추가합니다.

if($('#alertBox').length > 0){
  $('#alertBox').text('완료되었습니다.');
}

 

 

이 방식은 실무에서 매우 자주 사용하는 안정적인 패턴입니다.

 

 

5. 레이아웃/공통 스크립트 구조에서 발생하는 경우

Spring MVC, JSP, Thymeleaf, Vue, React 등 다양한 환경에서는 화면이 여러 파일로 나뉘어 렌더링됩니다.
이 과정에서 특정 페이지에는 없는 요소를 공통 스크립트에서 참조할 때 이 오류가 발생합니다.

해결 방법
공통 스크립트에서는 안전하게 length 체크 후 실행하거나 특정 페이지에서만 로직을 실행하도록 분기 처리를 합니다.

예시

if($('#pageType').val() === 'dashboard'){
  $('#userCount').addClass('updated');
}

 

 

 

6. id 또는 class 오타가 발생하는 경

다음처럼 단순 오타 때문에 오류가 발생하는 경우도 많습니다.

<div id="username"></div>

 

$('#usernmae').addClass('focus');

 

클래스도 마찬가지입니다.

이 경우 가장 빠른 해결 방법은 개발자 도구 Elements 탭에서 해당 id나 class가 실제로 존재하는지 확인하는 것입니다.