'XXX is not defined' ReferenceError 해결 — 원인과 빠른 진단

증상: XXX is not defined

콘솔에 이런 메시지가 뜨면 ReferenceError입니다.

Uncaught ReferenceError: myFunction is not defined
ReferenceError: process is not defined

해석은 단순합니다. "이 이름을 가진 변수나 함수를 찾을 수 없다". 즉 현재 코드가 실행되는 스코프에서 그 이름이 선언된 적이 없다는 뜻입니다.

왜 ReferenceError가 나는가

흔한 원인 6가지

• 오타 — getElementById를 getElementByID로. 대소문자 포함.
• import / require 누락 — 모듈을 안 불러오고 사용.
• 스코프 밖 접근 — 함수·블록 안에서 선언한 변수를 밖에서 사용.
• 스크립트 로드 순서 — 라이브러리보다 먼저 실행돼 아직 정의 전.
• 환경 불일치 — 브라우저에서 process, Node에서 window를 쓰는 등.
• TDZ — let/const 선언 전에 접근.

케이스별 해결

1) 오타·대소문자 확인

메시지의 이름을 그대로 복사해 코드에서 검색(Ctrl+F)하세요. 선언부와 철자가 다르면 그것이 원인입니다.

2) import / require 추가

// ESM
import { useState } from 'react';
// CommonJS
const express = require('express');

3) 스코프 바로잡기

function f() { const x = 1; }
console.log(x); // ReferenceError: x is not defined
// 해결: 바깥 스코프로 끌어올리거나 return으로 전달

4) 로드 순서

HTML에서 라이브러리를 사용 코드보다 먼저 로드하세요.

<script src="jquery.js"></script>
<script src="my-code.js"></script>  <!-- 나중 -->

5) 환경 차이 (브라우저 vs Node vs SSR)

같은 코드라도 실행 환경에 따라 존재하는 전역이 다릅니다. process is not defined는 브라우저에 Node 전역(process)이 없어서입니다. Vite는 import.meta.env, CRA는 빌드 타임에 process.env.REACT_APP_*를 치환합니다. 번들러 설정을 확인하세요.

// Vite
const key = import.meta.env.VITE_API_KEY;
// CRA
const key = process.env.REACT_APP_API_KEY;

반대로 window is not defined / document is not defined는 서버(Next.js의 SSR 등)에서 브라우저 전역을 쓴 경우입니다. 서버에는 window가 없으므로 가드를 넣습니다.

if (typeof window !== 'undefined') {
  localStorage.setItem('k', 'v');   // 브라우저에서만 실행
}

6) TDZ (let/const)

console.log(a); // ReferenceError
let a = 1;      // 선언 전 접근 불가
// 해결: 사용 전에 선언

원인별 비교

예방

• ESLint의 no-undef 규칙을 켜면 실행 전에 잡힙니다.
• 모듈 시스템(import/export)을 일관되게 사용.
• 에디터 자동완성을 활용해 철자 오류를 줄이세요.
• 전역 변수 의존을 줄이고 명시적으로 import.

자주 묻는 질문

Q1. is not defined와 undefined는 같은 건가요?

다릅니다. is not defined는 "이름 자체가 선언되지 않음"(ReferenceError)이고, undefined는 "선언은 됐지만 값이 없음"입니다. 진단 방향이 완전히 다릅니다.

Q2. 콘솔에서는 되는데 파일에선 not defined가 나요.

모듈 스코프 때문입니다. 콘솔의 전역과 달리 모듈 파일의 변수는 그 파일 안에서만 보입니다. 필요한 값은 import/export로 명시적으로 주고받으세요.

Q3. jQuery $ is not defined가 떠요.

jQuery 스크립트가 로드되기 전에 $를 썼기 때문입니다. jQuery <script>를 사용 코드보다 위에 두거나, defer 순서를 점검하세요.