結論
ReferenceError: X is not defined は「X という名前の変数・関数が、その場所からは見つからない」という意味です。綴りの違い・スコープの外・読み込み順・実行環境の違い(ブラウザと Node.js、ESM と CommonJS)のどれかが原因で、エラー文の X とファイル名・行番号を見れば、たいてい数分で原因を絞れます。
この記事でわかること
- 原因9つの見分け方と、それぞれの直し方(直したあとの出力つき)
- Node.js 22 と Chromium 153 で実際に出したエラーの原文
- script の順番・defer・async・module を5回ずつ読み込んだ実測
この記事で実際に動かしたもの:Node.js 22.23.4 で20本のスクリプト、Chromium 153(Playwright)で127.0.0.1 の自作サーバーから配った19枚の HTML、ESLint 10.14.0 と TypeScript 7.0.2 での事前検出。
ReferenceError は「名前が見つからない」ときのエラーです。似た名前の TypeError(Cannot read properties of undefined など)は「名前は見つかったが、中身が期待と違う」ときに出ます。まず次の図で、自分のエラーがどの原因に当たるかを絞り込みます。
flowchart LR
E{X は何?} --> A[自分の名前:<br>綴り・スコープ・順番]
E --> B[ライブラリ:<br>script の読み込み順]
E --> C[window・document:<br>Node.js で実行中]
E --> D[require・__dirname:<br>ESM かブラウザ]
やりたいことごとに、いちばん早い方法を先にまとめます。
| やりたいこと | いちばん早い方法 | 詳しい節 |
|---|---|---|
| is not defined の意味を知りたい | その場所から見える範囲に、その名前の宣言が無いという意味 | ReferenceErrorとは |
| どこで出ているか知りたい | エラー文の「ファイル名:行:列」を開く。DevTools はリンクをクリック | ReferenceErrorとは |
| 綴りか確かめたい | 宣言側の名前をコピーして検索。大文字小文字も区別される | 原因1 綴り |
| uncaught referenceerror(ブラウザ)を直したい | ライブラリの script を使う側より上に置く。defer を両方に付ける | 原因4 読み込み順 |
| onclick で function is not defined | type="module" なら addEventListener で登録する | 原因5 module |
| window・document is not defined(Node.js) | ブラウザで動かすコードを Node で実行している。typeof で分岐 | 原因6 Node.js |
| require is not defined | ESM なら import に書き換えるか、ファイルを .cjs にする | 原因8 ESM |
| __dirname is not defined | import.meta.dirname を使う(Node.js 20.11 以降) | 原因8 ESM |
| 実行する前に見つけたい | ESLint の no-undef か TypeScript を入れる | ESLint・TypeScript |
確認環境:Ubuntu 24.04.5 LTS の上で、Node.js 22.23.4 を使い、原因ごとに小さなスクリプト(.js・.mjs・"type": "module" のフォルダー)を作ってエラーを出し、直したあとの出力も取りました。ブラウザの挙動は、Node.js で書いた自作の HTTP サーバーを 127.0.0.1 に立て、Chromium 153.0.8010.12(playwright-core 1.63.0 から起動)で HTML を開いて確かめています。例外の文言は Chrome DevTools Protocol の Runtime.exceptionThrown で受け取った原文です。script の読み込み順の実験では、ライブラリのファイルだけ150ミリ秒遅らせて返し、9通りの書き方を5回ずつ読み込みました。事前の検出は ESLint 10.14.0(@eslint/js・globals)と TypeScript 7.0.2 で行いました。Safari と Firefox の文言は手元で動かしていないため、MDN の記載で確かめた範囲です。ESM と CommonJS の決まりは Node.js 公式ドキュメント、script の defer・async・module の決まりは MDN で確かめました。図は mermaid-cli 11.16.0 で描画を確かめています(確認日 2026年11月5日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「ReferenceError: X is not definedの原因と直し方」
ReferenceError: X is not definedとは(エラー文の読み方)
この節では、エラー文のどこを見れば原因の場所と名前が分かるのか、ブラウザごとの文言の違いが分かります。
ReferenceError は、JavaScript が名前(識別子)を探したのに、今いる場所から見える範囲(スコープ)のどこにも見つからなかったときに投げる例外です。X の部分には、見つからなかった名前がそのまま入ります。Node.js 22 で、宣言した名前と1文字違う名前を使うと、次のように出ました。
const userName = "taro";
console.log(usrName);
/dev/shm/t287/node/01_typo.js:2
console.log(usrName);
^
ReferenceError: usrName is not defined
at Object.<anonymous> (/dev/shm/t287/node/01_typo.js:2:13)
at Module._compile (node:internal/modules/cjs/loader:1781:14)
...
Node.js v22.23.4
読む順番は次の3つです。
- 1行目の「ファイル名:行番号」:エラーが起きた場所。上の例は 01_typo.js の2行目です。
- 「ReferenceError: 〇〇 is not defined」の〇〇:見つからなかった名前。自分で付けた名前か、window・require のような「環境が用意する名前」かで、原因の候補が大きく変わります。
- at の行の「:2:13」:2行目の13文字目。キャレット(^)の位置と同じです。node:internal で始まる行は Node.js 自身の内部なので、読み飛ばしてよい行です。
ブラウザでは先頭に Uncaught が付きます。「try...catch で受け止められなかった」という意味で、エラーの種類は同じです。Chromium 153 で、存在しない名前を参照する HTML を開いたときの原文です。
Uncaught ReferenceError: usrName is not defined
at http://127.0.0.1:36351/b8.html:2:9
Node.js の対話モード(REPL)でも、受け止められなかった例外には Uncaught が付きました。
> Uncaught ReferenceError: usrName is not defined
ブラウザ・実行環境ごとの文言
同じ原因でも、JavaScript エンジンによって文言が違います。検索するときは、自分の画面に出た文言のまま検索すると見つけやすくなります。
| 実行環境 | 名前が無いとき | 宣言より前に使ったとき | 確かめ方 |
|---|---|---|---|
| Chrome・Edge(V8) | X is not defined | Cannot access 'X' before initialization | Chromium 153 で実行 |
| Node.js(V8) | X is not defined | Cannot access 'X' before initialization | Node.js 22 で実行 |
| Firefox | X is not defined | can't access lexical declaration 'X' before initialization | MDN の記載 |
| Safari | Can't find variable: X | Cannot access uninitialized variable. | MDN の記載 |
iPhone や Mac の Safari で「Can't find variable」と出るのは、Chrome の「is not defined」と同じエラーです。直し方も同じです。
try...catch で受け止めたときの中身
ReferenceError はふつうの Error の仲間なので、try...catch で受け止めて名前と文言を取り出せます。
try {
missingVar;
} catch (e) {
console.log(e instanceof ReferenceError);
console.log(e.name);
console.log(e.message);
}
true
ReferenceError
missingVar is not defined
ただし、ReferenceError を try...catch で握りつぶして先へ進めるのは、原因を隠すだけです。ほとんどの場合、直すべきはコードの側です。
ReferenceErrorの原因の一覧(9つ)と見分け方
この節では、is not defined の原因を9つに分け、エラー文の X からどれに当たるかを素早く見分ける方法が分かります。
手元で再現できた原因を、出やすい順にまとめました。X が自分で付けた名前なら1〜3、ライブラリの名前なら4、window・document・require・process・__dirname なら6〜8を先に疑います。
| 原因 | X の例 | 出る場所 | 直し方の要点 |
|---|---|---|---|
| 1. 綴り・大文字小文字の違い | usrName・Username | どこでも | 宣言と同じ綴りにそろえる |
| 2. スコープの外から使っている | config・total | どこでも | 戻り値で渡す・外側で宣言する |
| 3. let・const を宣言より前に使う | apiKey(文言は Cannot access) | どこでも | 使う行を宣言の後ろへ移す |
| 4. script の読み込み順・defer・async | $・MyLib・Vue | ブラウザ | ライブラリを先に。両方 defer |
| 5. module の関数を onclick から呼ぶ | hello・submitForm | ブラウザ | addEventListener で登録する |
| 6. ブラウザ用のコードを Node で実行 | window・document・localStorage | Node.js | typeof で分岐・実行場所を分ける |
| 7. Node 用のコードをブラウザで実行 | require・process・module | ブラウザ | import に書き換える・ビルドツールの仕組みを使う |
| 8. ESM で CommonJS の名前を使う | require・__dirname・__filename・module | Node.js | import・import.meta.dirname・.cjs |
| 9. import 忘れ・strict mode の代入 | uuidv4・count | どこでも | import を足す・let で宣言する |
ブラウザにだけある名前
window・document・localStorage・alert
Node.js で使うと is not defined
手元の Node 22 では typeof window が "undefined"
Node.js(CommonJS)にだけある名前
require・module・exports・__dirname・__filename
ブラウザと ESM で使うと is not defined
process は Node.js 全体にあり、ブラウザに無い
どちらにもある名前は globalThis・console・setTimeout・fetch などです。両方で動かすコードでは、どちらか一方にしかない名前を直接書かないのが基本です。
原因1:綴り・大文字小文字の違い(is not defined javascript で最も多い)
この節では、いちばん多い綴りの違いを、素早く見つける方法と直したあとの結果が分かります。
JavaScript の名前は大文字と小文字を区別します。userName と username と UserName は、すべて別の名前です。冒頭の例のように1文字抜けた usrName でも、JavaScript は「別の名前が使われた」としか判断できず、is not defined になります。
直し方は、宣言側の名前をコピーして使う側に貼ることです。直したあとの実行結果です。
const userName = "taro";
console.log(userName);
taro
綴りの違いは、目で探すより道具に任せるほうが早く見つかります。
- エディターの検索:エラー文の X(usrName)で検索し、1か所しか出てこなければ綴りの違いが濃厚です。
- TypeScript:TypeScript 7.0.2 で同じコードを型チェックすると、
error TS2552: Cannot find name 'usrName'. Did you mean 'userName'?と、正しい候補まで示されました(後の節で詳しく)。 - 関数名・メソッド名:getElementById を getElementByID と書くと、こちらは「document.getElementByID is not a function」という TypeError になります。オブジェクトの中のメソッド名の間違いは ReferenceError ではなく TypeError になる点も、見分けの手がかりです。
原因2:スコープの外から使っている(関数・ブロック)
この節では、関数やブロックの中で宣言した変数を外から使ったときのエラーと、値を外へ渡す直し方が分かります。
let・const・関数の引数・関数の中の var は、宣言した関数やブロック({ } の中)からしか見えません。関数の中で作った config を、関数の外で読むと次のようになりました。
function setup() {
const config = { port: 3000 };
}
setup();
console.log(config.port);
ReferenceError: config is not defined
at Object.<anonymous> (/dev/shm/t287/node/02_scope.js:5:13)
if 文や for 文の { } も同じです。let で宣言した total は、ブロックの外では見えません。
if (true) {
let total = 10;
}
console.log(total);
ReferenceError: total is not defined
at Object.<anonymous> (/dev/shm/t287/node/03_block.js:4:13)
直し方は、目的によって3通りです。
- 戻り値で渡す(いちばんおすすめ):
function setup() { return { port: 3000 }; } const config = setup(); - 使う場所に合わせて外側で宣言する:
let total; if (cond) { total = 10; } - 引数で渡す:別の関数で使うなら、
run(config)のように引数で受け渡す。
エラーを消すためだけに直すと、別の不具合が出る
config = {...} と宣言なしで代入し、グローバル変数にしてしまう。strict mode や ESM では、今度はそこで is not defined になる見分ける問い:「この値は、どの関数が作って、どこで使うのか」
関数が外側の変数を覚えておく仕組み(クロージャ)は、関連記事「JavaScript クロージャとは?使いどころ7例をコード付きで図解」で扱っています。
原因3:let・constを宣言より前に使う(TDZ)とvarとの違い
この節では、宣言より前に変数を使ったときに出る「Cannot access before initialization」と、var・関数宣言との違いが分かります。
let・const・class は、宣言の行が実行されるまでの間、名前はあっても使えない状態になります。この区間を TDZ(Temporal Dead Zone、一時的なデッドゾーン)と呼びます。文言は is not defined ではなく、次のようになりました。
console.log(apiKey);
const apiKey = "abc";
ReferenceError: Cannot access 'apiKey' before initialization
at Object.<anonymous> (/dev/shm/t287/node/04_tdz.js:1:13)
同じ ReferenceError でも、「is not defined」は名前が見つからない、「Cannot access ... before initialization」は名前はあるが順番が早すぎる、という違いです。後者は、使う行を宣言の後ろへ移せば直ります。
宣言の種類ごとに、宣言より前で使ったときの結果を Node.js 22 で並べました。
| 宣言の書き方 | 宣言より前で使った結果 | 理由 |
|---|---|---|
| var apiKey = "abc" | undefined(エラーにならない) | var は宣言が先頭に巻き上げられ、undefined で初期化される |
| const apiKey = "abc" | ReferenceError: Cannot access 'apiKey' before initialization | TDZ の中 |
| let x = x + 1 | ReferenceError: Cannot access 'x' before initialization | 右辺の x を読む時点で、まだ初期化されていない |
| function hello() {} | "hoisted"(呼び出せる) | 関数宣言は本体ごと巻き上げられる |
| const greet = () => "hi" | ReferenceError: Cannot access 'greet' before initialization | 関数式・アロー関数は const の決まりに従う |
| class User {} | ReferenceError: Cannot access 'User' before initialization | class も TDZ がある |
var だとエラーにならず undefined のまま進んでしまうため、かえって不具合に気づきにくくなります。var に戻してエラーを消すのではなく、const・let のまま順番を直すほうが安全です。
もう1つ覚えておきたいのは、typeof との関係です。typeof は、宣言の無い名前ならエラーにせず "undefined" を返しますが、TDZ の中の名前には ReferenceError を投げました。
console.log(typeof notDeclared); // 宣言なし
try { typeof a; let a; } catch (e) { console.log(e.message); }
undefined
Cannot access 'a' before initialization
「関数の中から、後で宣言する const を参照している」場合は、エラーが出るかどうかは呼び出した時点で決まります。宣言の行が実行された後に関数を呼べばエラーにはなりません。行の並びではなく、実行される順番で考えると分かりやすくなります。
原因4:scriptの読み込み順・defer・async(Uncaught ReferenceErrorの実測)
この節では、ブラウザでライブラリの名前($・MyLib など)が is not defined になる理由を、9通りの書き方を5回ずつ読み込んだ実測で確かめられます。
ブラウザでは、script タグに書いたファイルがどの順番で実行されるかで結果が変わります。ライブラリ(lib.js が window.MyLib を作る)を、使う側(app.js が MyLib.version を読む)より後に実行すると、使う時点ではまだ MyLib がありません。jQuery の「$ is not defined」もこの形が多い原因です。
// lib.js
window.MyLib = { version: "1.0" };
// app.js
console.log("MyLib " + MyLib.version);
127.0.0.1 の自作サーバーで lib.js だけを150ミリ秒遅らせて返し、Chromium 153 で各ページを5回ずつ開きました。
| head の書き方 | エラー | 正しく動いた | 理由 |
|---|---|---|---|
| app.js → lib.js(順番が逆) | 5/5 | 0/5 | 使う側が先に実行される |
| lib.js → app.js | 0/5 | 5/5 | 書いた順に実行される |
| lib.js に async、app.js はそのまま | 5/5 | 0/5 | async は届いた時点で実行。順番の保証が無い |
| lib.js に defer、後ろにインラインの script | 5/5 | 0/5 | インラインは defer を待たずにすぐ実行される |
| lib.js・app.js の両方に defer | 0/5 | 5/5 | defer 同士は書いた順に実行される |
| 両方に async | 5/5 | 0/5 | 小さい app.js が先に届いて実行された |
| lib.js に defer、app.js は type="module" | 0/5 | 5/5 | module も defer と同じく書いた順に実行される |
| lib.js に defer、インラインは DOMContentLoaded の中 | 0/5 | 5/5 | defer は DOMContentLoaded より前に終わる |
| body の末尾に lib.js → app.js | 0/5 | 5/5 | 書いた順に実行される |
エラーになったときの原文です。lib.js 側には問題が無く、エラーは使う側の app.js の1行目で出ます。
Uncaught ReferenceError: MyLib is not defined
at http://127.0.0.1:36351/app.js:1:24
インラインの script で出た場合は、HTML のファイル名と行番号が示されます。
Uncaught ReferenceError: MyLib is not defined
at http://127.0.0.1:36351/p4.html:2:68
1順番さえ合えば毎回動く
同期の script を正しい順に並べた形と、両方 defer の形は、5回とも正しく動いた。
2async は依存のあるファイルに向かない
ライブラリに async を付けた形は5回とも失敗した。届く速さで順番が変わるため、回線によっては動いたり動かなかったりする。
3インラインに defer は効かない
src の無い script に defer を付けても意味が無い(MDN にも明記)。DOMContentLoaded の中で使えば待てる。
正しく動く書き方の例です。
<head>
<script defer src="lib.js"></script>
<script defer src="app.js"></script>
</head>
CDN から読み込むライブラリでは、ネットワークの都合で読み込み自体に失敗することもあります。その場合も、使う側で同じ ReferenceError が出ます。DevTools の[ネットワーク]タブで、ライブラリのファイルが 200 で届いているかを最初に見ます。404 や「(failed)」なら、URL の誤り・広告ブロッカー・社内ネットワークの制限を疑います。
Chrome DevTools で順番を確かめる手順
F12 で DevTools を開き、[コンソール]を見る
赤い「Uncaught ReferenceError」の行の右端にある「app.js:1」のようなリンクをクリックすると、該当の行が開く。
[ネットワーク]タブで再読み込みする
種類を「JS」に絞り、ライブラリのファイルがステータス 200 で届いているか、使う側より先に届いているかを見る。
コンソールで名前を直接打つ
ページを読み込み終えた後に typeof MyLib と打つ。"object" なら読み込み順の問題、"undefined" ならライブラリ自体が読み込まれていない。
[要素]タブで script の並びを確かめる
テンプレートやプラグインが script を自動で差し込んでいる場合、ソースと実際の並びが違うことがある。表示中の HTML で順番を見る。
原因5:type="module"の関数がonclickからis not definedになる
この節では、HTML の onclick 属性から module の中の関数を呼ぶとエラーになる理由と、2通りの直し方が分かります。
type="module" の script で宣言した変数・関数は、その module の中だけで有効です。window(グローバル)には載りません。そのため、HTML の onclick="hello()" から呼ぶと、ボタンを押した時点でエラーになりました。
<script type="module">
function hello() { console.log("hello called"); }
</script>
<button id="btn" onclick="hello()">押す</button>
Uncaught ReferenceError: hello is not defined
at HTMLButtonElement.onclick (http://127.0.0.1:36351/b1.html:4:36)
at の行に HTMLButtonElement.onclick とあるのが、この原因の目印です。ページを開いたときではなく、ボタンを押したときに初めて出るため、気づくのが遅れがちです。
直し方は2通りあり、どちらも Chromium 153 でボタンを押して「hello called」が出ることを確かめました。
直し方A(おすすめ):module の中で addEventListener を使って登録します。HTML に関数名を書かないので、名前の見え方に左右されません。
<button id="btn">押す</button>
<script type="module">
function hello() { console.log("hello called"); }
document.getElementById("btn").addEventListener("click", hello);
</script>
直し方B:どうしても onclick を残すなら、関数を window に載せます。ほかの script と名前がぶつかる可能性があるため、数を増やさないようにします。
<script type="module">
function hello() { console.log("hello called"); }
window.hello = hello;
</script>
<button id="btn" onclick="hello()">押す</button>
module の変数が別の script から見えないことも確かめました。module で var shared = 1 と書いても window.shared は undefined のままで、後から実行した普通の script で shared を読むと、次のエラーになりました。普通の script で同じように書いた var は、window に載りました。
module window.shared=undefined
Uncaught ReferenceError: shared is not defined
at http://127.0.0.1:36351/use.js:1:13
また、module の script は file:// で HTML を直接開くと CORS のエラーで読み込めません(MDN に記載)。読み込みに失敗すると、その module で定義するはずの関数も無いため、同じ is not defined が出ます。module を使うページは、ローカルの開発サーバー(127.0.0.1)経由で開くのが前提です。
原因6:Node.jsでwindow・document is not definedになる
この節では、ブラウザ用のコードを Node.js で動かしたときのエラーと、実行場所によって処理を分ける書き方が分かります。
window・document・localStorage・alert は、ブラウザが用意する名前です。Node.js にはありません。ブラウザ向けのコードをそのまま node コマンドで実行すると、次のようになりました。
ReferenceError: window is not defined
at Object.<anonymous> (/dev/shm/t287/node/07_window.js:1:13)
ReferenceError: document is not defined
at Object.<anonymous> (/dev/shm/t287/node/08_document.js:1:1)
手元の Node.js 22 で、それぞれの名前を typeof で調べた結果です。
typeof window → undefined
typeof document → undefined
typeof globalThis → object
typeof process → object
この原因が出やすいのは次の場面です。
- Next.js・Nuxt などのサーバーサイドレンダリング:コンポーネントの処理がサーバー(Node.js)でも実行されるため、最上位に window を書くとサーバー側で落ちます。ブラウザでだけ動く処理は、useEffect の中やクライアント側の処理に移します。
- テスト:Jest・Vitest の既定の環境は Node.js です。DOM を使うテストは、jsdom などの環境を指定して動かします。
- ブラウザ用のライブラリを Node.js のスクリプトで読み込んだ:Node.js 用の版や別のライブラリを選びます。
どちらの環境でも動かすコードは、typeof で存在を確かめてから使います。typeof は宣言の無い名前でもエラーにならないためです。
const isBrowser = typeof window !== "undefined";
console.log("isBrowser:", isBrowser);
console.log("globalThis === global:", globalThis === global);
if (typeof document !== "undefined") {
document.title = "x";
} else {
console.log("document なし: ブラウザ以外で実行中");
}
isBrowser: false
globalThis === global: true
document なし: ブラウザ以外で実行中
グローバルオブジェクトを指したいだけなら、window や global ではなく globalThisを使うと、ブラウザでも Node.js でも同じ書き方で動きます。
原因7:ブラウザでrequire・process is not definedになる
この節では、Node.js 用の書き方をブラウザで実行したときのエラーと、ブラウザでの代わりの書き方が分かります。
require・module・exports・process は Node.js が用意する名前です。ブラウザで直接実行すると、Chromium 153 では次のようになりました。
Uncaught ReferenceError: require is not defined
at http://127.0.0.1:36351/b2.html:2:20
Uncaught ReferenceError: process is not defined
at http://127.0.0.1:36351/b3.html:2:21
同じページで typeof を調べると、window・document・globalThis は "object"、process と require は "undefined" でした。
| ブラウザで出た名前 | よくある場面 | 直し方 |
|---|---|---|
| require is not defined | npm のパッケージを script タグで直接読み込んだ | import に書き換え、Vite・webpack などでまとめる |
| process is not defined | process.env.API_URL で環境変数を読んだ | Vite は import.meta.env、ほかはビルドツールの置き換え機能を使う |
| module is not defined | module.exports をブラウザ向けのファイルに書いた | export に書き換える |
| exports is not defined | TypeScript を CommonJS 向けに変換したファイルをそのまま読み込んだ | tsconfig の module を ESNext などにする |
process.env をそのままブラウザで読めるのは、ビルドツールがビルドのときに文字列へ置き換えてくれた場合だけです。ブラウザに process というオブジェクトがあるわけではありません。
原因8:ESMでrequire・__dirname is not definedになる(Node.js)
この節では、Node.js の ES モジュール(ESM)で require・__dirname が使えない理由と、それぞれの置き換え方が分かります。
Node.js のファイルには、CommonJS(require で読み込む)と ESM(import で読み込む)の2つの形式があります。require・module・exports・__dirname・__filename は CommonJS にだけある名前で、ESM として読み込まれたファイルでは使えません(Node.js 公式ドキュメント「Differences between ES modules and CommonJS」)。
.mjs のファイルで使うと、Node.js 22 は次のように答えました。文言に in ES module scope が付くのが目印です。
ReferenceError: require is not defined in ES module scope, you can use import instead
at file:///dev/shm/t287/node/11_require.mjs:1:12
ReferenceError: __dirname is not defined in ES module scope
at file:///dev/shm/t287/node/12_dirname.mjs:1:13
ReferenceError: module is not defined in ES module scope
at file:///dev/shm/t287/node/14_exports.mjs:1:1
package.json に "type": "module" があるフォルダーの .js では、理由の説明まで出ました。
ReferenceError: require is not defined in ES module scope, you can use import instead
This file is being treated as an ES module because it has a '.js' file extension and '/dev/shm/t287/node/esmpkg/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.
もう1つ見落としやすいのが、package.json に type が無くても、ファイルの中に import 文があると ESM として扱われることです。Node.js 22.7.0 以降は、この「構文の検出」が既定で有効です(Node.js 公式ドキュメント「Packages」)。1行目に import、2行目に require と混ぜて書いた .js は、次のようになりました。
import fs from "node:fs";
const p = require("node:path");
ReferenceError: require is not defined in ES module scope, you can use import instead
at file:///dev/shm/t287/node/mix.js:2:11
at の行が file:/// で始まっていれば ESM、パスだけ(Object.<anonymous>)なら CommonJS として実行されています。どちらの形式で動いているかは、この行で見分けられます。
ESM での置き換え方(実行結果つき)
| CommonJS の書き方 | ESM での書き方 | 補足 |
|---|---|---|
| const fs = require("fs") | import fs from "node:fs" | CommonJS のパッケージも import で読める場合が多い |
| __dirname | import.meta.dirname | v20.11.0・v21.2.0 で追加。v22.16.0 で実験的の扱いが外れた |
| __filename | import.meta.filename | 同上。file: のモジュールだけで使える |
| (以前の版の Node.js) | path.dirname(fileURLToPath(import.meta.url)) | import.meta.dirname が無い版向け |
| require がどうしても要る | createRequire(import.meta.url) | node:module から読み込む |
| module.exports = {...} | export default {...} | 名前付きなら export const |
import { createRequire } from "node:module";
import path from "node:path";
import { fileURLToPath } from "node:url";
console.log(import.meta.dirname);
console.log(import.meta.filename);
console.log(path.dirname(fileURLToPath(import.meta.url)));
const require = createRequire(import.meta.url);
console.log(typeof require("node:fs").readFileSync);
/dev/shm/t287/node
/dev/shm/t287/node/13_fixdirname.mjs
/dev/shm/t287/node
function
ESM に書き換えたくない場合は、ファイル名を .cjs に変えると、"type": "module" のフォルダーの中でも CommonJS として動きます。上のエラーが出た app.js を app.cjs にコピーして実行すると、エラーは出ず、終了コードは0でした。
ESM と CommonJS の混在の詳しい解決方法は関連記事「Node.js ESMとCommonJSの違い|import混在の解決表」で、import・export の書き方の基本は関連記事「JavaScript import/export入門|ESMとCommonJSの違い」で扱っています。
原因9:import忘れ・strict modeの代入・jQueryの$
この節では、残りの3つの原因(import の書き忘れ、宣言なしの代入、$ is not defined)の再現と直し方が分かります。
import を書き忘れた
パッケージの関数を使っているのに import が無いと、その名前は定義されていません。
ReferenceError: uuidv4 is not defined
at file:///dev/shm/t287/node/15_fetch_import.mjs:1:1
直し方は、ファイルの先頭に import を足すことです。名前付きの export なら import { v4 as uuidv4 } from "uuid"; のように、パッケージが公開している名前で読み込みます。パッケージ自体が入っていない場合は、ReferenceError ではなく「Cannot find package」「Cannot find module」のエラーになります。こちらは関連記事「Node.js Cannot find moduleの原因と直し方」で扱っています。
strict mode で宣言なしに代入した
宣言の無い名前への代入は、strict mode では ReferenceError になります。ESM と class の中は、書かなくても常に strict mode です。
"use strict";
count = 1;
ReferenceError: count is not defined
at Object.<anonymous> (/dev/shm/t287/node/09_strict.js:2:7)
"use strict" を消して同じコードを実行すると、エラーにならず 1 1(count と globalThis.count)と出ました。宣言を忘れた変数が、気づかないうちにグローバル変数になっている状態です。CommonJS から ESM に移したとたんにこのエラーが出るのは、もともと宣言漏れがあったからです。let count = 1; と宣言すれば直ります。
$ is not defined(jQuery)
Node.js で実行しても、ブラウザで jQuery より先に実行しても、同じ文言になります。
ReferenceError: $ is not defined
ブラウザなら原因4の読み込み順、WordPress なら jQuery を noConflict モードで読み込んでいるため $ ではなく jQuery という名前で使う必要がある場合があります。jQuery(function ($) { ... }); のように書くと、関数の中では $ が使えます。
HTML の id がグローバル変数に見える場合
ブラウザには、id を付けた要素を同じ名前のグローバル変数として参照できる仕組みがあります。手元では、body の中で <p id="msg"> の後ろに置いた script から msg.tagName を読むと "P" が返りました。一方、同じ script を head に置くと、要素がまだ読み込まれていないため Uncaught ReferenceError: msg is not defined になりました。この仕組みに頼らず、document.getElementById で取得するほうが、置き場所に左右されません。
ESLint・TypeScriptでReferenceErrorを実行前に見つける
この節では、ReferenceError を実行する前に見つける設定と、手元で検出できた結果が分かります。
ReferenceError は、そのコードが実行されるまで出ません。ボタンを押したときだけ、特定の条件のときだけ通るコードは、テストで通らないと本番で初めて出ます。ESLint の no-undef ルールと TypeScript は、実行せずに見つけられます。
ESLint(no-undef・no-use-before-define)
ESLint 10.14.0 で、推奨設定(no-undef を含む)に no-use-before-define を足し、Node.js 用とブラウザ用で使える名前(globals)を分けて設定しました。
// eslint.config.mjs
import js from "@eslint/js";
import globals from "globals";
export default [
js.configs.recommended,
{ files: ["*.js"],
languageOptions: { sourceType: "commonjs", globals: { ...globals.node } },
rules: { "no-use-before-define": "error", "no-unused-vars": "off" } },
{ files: ["browser/**/*.js"],
languageOptions: { sourceType: "module", globals: { ...globals.browser } } },
];
この記事の例に対して npx eslint . を実行した結果です。綴り・スコープ・TDZ・Node.js での window を、実行せずに見つけられました。
/dev/shm/t287/lint/01_typo.js
2:13 error 'usrName' is not defined no-undef
/dev/shm/t287/lint/02_scope.js
5:13 error 'config' is not defined no-undef
/dev/shm/t287/lint/04_tdz.js
1:13 error 'apiKey' was used before it was defined no-use-before-define
/dev/shm/t287/lint/07_window.js
1:13 error 'window' is not defined no-undef
ブラウザ用のフォルダーに置いた、require と process を使うファイルも検出されました。
/dev/shm/t287/lint/browser/page.js
1:12 error 'require' is not defined no-undef
1:39 error 'process' is not defined no-undef
globals の設定を間違えると、本当は使えない名前を見逃します。手元でも、最初にすべての .js へ Node.js の globals を当てる設定にしたところ、ブラウザ用のファイルの require と process が検出されませんでした。ブラウザで動くファイルには globals.browser だけを当てるよう、files の範囲を分けます。
TypeScript
TypeScript 7.0.2 で、綴りを間違えたコードを型チェックすると、正しい名前の候補まで表示されました。
$ npx tsc --noEmit --lib es2022,dom t.ts
t.ts(2,13): error TS2552: Cannot find name 'usrName'. Did you mean 'userName'?
lib に dom を入れない設定で window を使うと、error TS2304: Cannot find name 'window'. になりました。TypeScript では、tsconfig の lib と types が「その環境にある名前」の一覧の役割をします。Node.js 用なら @types/node、ブラウザ用なら dom を指定します。
- 1ESLint の no-undef を有効にする推奨設定(js.configs.recommended)に含まれている
- 2実行環境ごとに globals を分けるNode.js のファイルに globals.node、ブラウザのファイルに globals.browser
- 3var をやめ、const・let で宣言する宣言前の使用がエラーとして見つかるようになる
- 4CI で ESLint と tsc --noEmit を実行するまれにしか通らないコードの ReferenceError も、マージ前に止まる
よくあるエラー原文と判断表(どの直し方を選ぶか)
この節では、エラー文の原文から原因と直し方を引ける表と、直し方を選ぶ順番が分かります。
| エラー原文 | 環境 | 原因 | 直し方 |
|---|---|---|---|
| ReferenceError: usrName is not defined | どこでも | 綴りの違い | 宣言と同じ綴りにする |
| ReferenceError: Cannot access 'apiKey' before initialization | V8 | TDZ | 宣言の後ろで使う |
| Uncaught ReferenceError: MyLib is not defined | ブラウザ | 読み込み順・async | ライブラリを先に。両方 defer |
| Uncaught ReferenceError: hello is not defined at HTMLButtonElement.onclick | ブラウザ | module の関数を onclick から呼んだ | addEventListener で登録 |
| ReferenceError: window is not defined | Node.js | ブラウザ用のコード | typeof で分岐・クライアント側へ移す |
| Uncaught ReferenceError: require is not defined | ブラウザ | Node.js 用のコード | import とビルドツール |
| ReferenceError: require is not defined in ES module scope, you can use import instead | Node.js | ESM で require | import に書き換えるか .cjs にする |
| ReferenceError: __dirname is not defined in ES module scope | Node.js | ESM で __dirname | import.meta.dirname |
| ReferenceError: Can't find variable: X | Safari | is not defined と同じ | 上の各行と同じ |
似ているが別のエラーも並べておきます。手元の Node.js 22 では、次のように出ました。
| エラー | 意味 | ReferenceError との違い |
|---|---|---|
| TypeError: Cannot read properties of null (reading 'foo') | null・undefined のプロパティを読んだ | 名前はあるが中身が null・undefined |
| TypeError: obj.missing is not a function | 関数でないものを呼んだ | オブジェクトの中に無いメソッド名は TypeError |
| undefined(エラーにならない) | 無いプロパティを読んだ(obj.missing) | プロパティが無いだけでは例外にならない |
Cannot read properties of undefined の原因と直し方は、関連記事「Cannot read properties of undefined原因7つ」で扱っています。
直し方を選ぶ順番
次の順で確かめると、ほとんどのケースで原因に行き着きます。
- 1文言に in ES module scope がある → ESM の問題import・import.meta.dirname・.cjs
- 2Cannot access ... before initialization → 順番の問題使う行を宣言の後ろへ
- 3X が window・document・localStorage → Node.js で実行しているSSR・テスト環境・typeof の分岐
- 4X が require・process・module → ブラウザで実行しているimport とビルドツールの仕組み
- 5X がライブラリの名前 → 読み込み順と読み込みの成否ネットワークのタブで 200 か、script の順番と defer
- 6at に onclick がある → module の関数を HTML から呼んでいるaddEventListener
- 7X が自分の名前 → 綴り、次にスコープ、次に importエディターで検索。宣言の場所と使う場所の { } を見比べる
症状から引く表
| 症状 | 考えられる原因 | 直し方 |
|---|---|---|
| 手元では動くのに、本番や別の回線でだけ出る | async で順番が変わる・CDN の読み込み失敗 | defer に変え、ネットワークのタブで確かめる |
| ボタンを押したときだけ出る | module の関数を onclick から呼んでいる | addEventListener で登録する |
| npm run dev では動くのに build で落ちる | SSR でサーバー側でも実行されて window が無い | ブラウザでだけ動く処理に移す |
| テストでだけ document is not defined | テストの既定の環境が Node.js | jsdom などの環境を指定する |
| package.json に "type": "module" を足したら出た | .js がすべて ESM になった | import に書き換えるか、該当ファイルを .cjs にする |
| Safari でだけ Can't find variable | そのブラウザに無い機能・名前を使っている | typeof で存在を確かめ、対応状況を MDN で見る |
よくある質問
Q. ReferenceError: X is not defined とはどういう意味ですか? A. X という名前の変数・関数が、その場所から見える範囲(スコープ)に見つからない、という意味です。綴りの違い、スコープの外からの参照、読み込み順、実行環境の違いが主な原因です。
Q. Uncaught ReferenceError の Uncaught は何ですか? A. 「try...catch で受け止められなかった」という意味です。エラーの種類は ReferenceError で、Uncaught が付かない場合と原因・直し方は同じです。
Q. is not defined と undefined は何が違いますか? A. is not defined は「名前そのものが無い」ためのエラーで、処理が止まります。undefined は「名前はあるが値が入っていない」状態で、エラーではありません。宣言だけして値を入れていない変数や、無いプロパティを読んだ結果が undefined です。
Q. 変数があるか、エラーを出さずに確かめる方法はありますか?
A. typeof X !== "undefined" で確かめられます。typeof は宣言の無い名前でもエラーにならず "undefined" を返します。ただし、let・const の宣言より前(TDZ)では typeof でも ReferenceError になりました。
Q. require is not defined を直すにはどうすればよいですか? A. Node.js で「in ES module scope」と出るなら、import に書き換えるか、ファイルを .cjs にします。ブラウザで出るなら、require はブラウザに無いので、import に書き換えて Vite・webpack などのビルドツールでまとめます。
Q. __dirname is not defined の代わりは何ですか?
A. ESM では import.meta.dirname を使います。Node.js 20.11.0・21.2.0 で追加され、22.16.0 で実験的の扱いが外れました。それより前の版では path.dirname(fileURLToPath(import.meta.url)) を使います。
Q. onclick で function is not defined になるのはなぜですか? A. 関数を type="module" の script で宣言していると、その関数は module の中だけで有効で、HTML の onclick からは見えないためです。module の中で addEventListener を使って登録すると直ります。
Q. jQuery の $ is not defined はどう直しますか? A. jQuery を読み込む script を、$ を使う script より上に置きます。DevTools のネットワークのタブで jQuery のファイルが 200 で届いているかも確かめます。WordPress では jQuery(function ($) { ... }) の形で書くと関数の中で $ を使えます。
Q. var にすればエラーは消えますか? A. 宣言より前に使っている場合は消えますが、値は undefined のまま進むため、不具合を見つけにくくなります。const・let のまま、使う順番を直すほうが安全です。
Q. Safari の Can't find variable は別のエラーですか? A. 同じ ReferenceError です。MDN によると、Chrome・Edge・Firefox が「X is not defined」と出す場面で、Safari は「Can't find variable: X」と出します。
Q. ReferenceError を事前に防ぐには何を入れればよいですか? A. ESLint の no-undef(推奨設定に含まれる)と、TypeScript の型チェックが効果的です。手元の例では、綴り・スコープ・TDZ・環境の違いのすべてを実行前に検出できました。
まとめ
- ReferenceError: X is not defined は、X という名前がその場所から見つからないという意味。ブラウザでは先頭に Uncaught が付き、Safari では Can't find variable: X と出る。
- X が自分の名前なら綴り・スコープ・import、ライブラリの名前なら読み込み順、window・document なら Node.js で実行、require・process ならブラウザで実行、in ES module scope なら ESM の問題を疑う。
- let・const を宣言より前に使うと、文言は Cannot access 'X' before initialization になる。var に戻さず、使う順番を直す。
- Chromium 153 の実測では、ライブラリに async を付けた形とインラインの script は5回とも失敗し、両方 defer の形と正しい順の同期読み込みは5回とも成功した。type="module" の関数は onclick から見えない。
- ESM では import・import.meta.dirname・.cjs で置き換える。ESLint の no-undef と TypeScript で、実行前に見つけられる。
次に読むとよい記事です。ESM と CommonJS をまたぐ問題は関連記事「Node.js ESMとCommonJSの違い|import混在の解決表」で、似た TypeError は関連記事「Cannot read properties of undefined原因7つ」で扱っています。
参考・出典
確認日はいずれも 2026年11月5日です。
- MDN「ReferenceError: "x" is not defined」:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Not_defined
- MDN「ReferenceError: can't access lexical declaration 'X' before initialization」:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_lexical_declaration_before_init
- MDN「ReferenceError」:https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError
- MDN「<script>: スクリプト要素」(defer・async・type="module"):https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script
- MDN「JavaScript modules」:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
- Node.js「Modules: ECMAScript modules」(Differences between ES modules and CommonJS・import.meta.dirname):https://nodejs.org/api/esm.html
- Node.js「Modules: Packages」("type" フィールド・構文の検出):https://nodejs.org/api/packages.html
- Node.js「Modules: node:module API」(createRequire):https://nodejs.org/api/module.html
- ESLint「no-undef」:https://eslint.org/docs/latest/rules/no-undef
- ESLint「no-use-before-define」:https://eslint.org/docs/latest/rules/no-use-before-define
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「ReferenceError: X is not definedの原因と直し方」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。