Linuxの開発サーバーで出るNode.jsのENOSPCの直し方

​​Node.js​Linux,Vite,トラブルシュート

Linux で Vite などの開発サーバーを起動したときに出る ENOSPC: System limit for number of file watchers reached は、ファイルの変更を知らせる Linux の仕組み(inotify)で見張れるファイルの数が、カーネルの上限 fs.inotify.max_user_watches に届いたというエラーです。保存しても画面が更新されない(ホットリロードが効かない)ときに、ターミナルにこの行が並んでいたら、上限を上げるか、見張るファイルを減らすと直ります。

私は検証環境で上限をわざと小さくしてこのエラーを起こし、出た文面と、2つの直し方でエラーが消え、ファイルの変更がブラウザに届くようになることを確かめました。

補足

検証環境は Ubuntu 24.04(カーネル 6.18)、Node.js 22.23.4、Vite 8.3.8 です。webpack や Next.js など Vite 以外の開発サーバー、Docker のコンテナーや WSL の中での動作、マシンを再起動したあとの設定の残り方は試していません。

開発サーバーで出たエラーの文面

検証用に、index.html と src/main.js のほかに、src/ の下に JavaScript のファイルを400個、fixtures/ の下に JSON のファイルを500個置いたプロジェクトを作りました。src/main.js は src/dir40/m1.js の値を読み込んで、ページの見出しに表示します。

検証環境の上限は 128415 でした。このままではエラーにならないので、上限を 100 に下げてから、Vite の開発サーバーを起動しました。

text
$ sudo sysctl fs.inotify.max_user_watches=100
fs.inotify.max_user_watches = 100
$ npx vite --port 5173

  VITE v8.3.8  ready in 159 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
file watcher error: ENOSPC: System limit for number of file watchers reached, watch '/path/to/app/fixtures/set1/case40.json'
file watcher error: ENOSPC: System limit for number of file watchers reached, watch '/path/to/app/fixtures/set1/case41.json'
file watcher error: ENOSPC: System limit for number of file watchers reached, watch '/path/to/app/fixtures/set1/case42.json'
(以下、同じ形の行が続く)

watch '…' のパスは、検証環境の作業ディレクトリを /path/to/app に置き換えています。この実行では、同じ形の行が 865 行並びました。

開発サーバーは止まらず、ページは開けました。ただし、見張れなかったファイルの中に src/dir40/m1.js も入っていました。ブラウザでページを開いたまま、このファイルの値を 1 から 100 に書き換えても、3秒たっても見出しは v1 = 1 のままでした。エラーの行は起動したときに流れていくだけなので、「保存しても画面が変わらない」という形で気づくことになります。

Node.js の fs.watch で出るときの形

Vite は、ファイルの変更を chokidar というライブラリで見張っています(公式ドキュメントの server.watch の説明)。chokidar 3.6.0 の README によると、chokidar は Linux では Node.js の fs.watch を使っています。公式ドキュメントの fs.watch の「Availability」にあるとおり、Linux では inotify を使ってファイルの変更を受け取ります。

上限を 100 にしたまま、次の hold.mjs で fixtures/ のファイルを見張り、上限まで使い切りました。

js
// 上限に届くまで fixtures のファイルを見張り、見張りを使い切った状態にする
import { readdirSync, watch } from 'node:fs';
for (const d of readdirSync('fixtures')) {
  for (const f of readdirSync(`fixtures/${d}`)) {
    try { watch(`fixtures/${d}/${f}`); } catch {}
  }
}
setTimeout(() => process.exit(0), 3000);

その状態で、1つのファイルを fs.watch で見張るだけの次の watch-one.mjs を実行すると、エラーで終わりました(パスの一部を置き換えています)。

js
// Node.js の fs.watch で1つのファイルを見張る
import { watch } from 'node:fs';
watch(process.argv[2], () => console.log('changed'));
console.log('watching', process.argv[2]);
text
$ node hold.mjs & sleep 1; timeout 2 node watch-one.mjs src/main.js; wait
node:internal/fs/watchers:254
    const error = new UVException({
                  ^

Error: ENOSPC: System limit for number of file watchers reached, watch 'src/main.js'
    at FSWatcher.<computed> (node:internal/fs/watchers:254:19)
    at watch (node:fs:2554:36)
    at file:///path/to/app/watch-one.mjs:3:1
    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:681:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:117:5) {
  errno: -28,
  syscall: 'watch',
  code: 'ENOSPC',
  path: 'src/main.js',
  filename: 'src/main.js'
}

Node.js v22.23.4

ENOSPC(errno: -28)は、本来は「No space left on device(デバイスに空きがない)」を表すエラーコードです。Linux 6.18 のソース(fs/notify/inotify/inotify_user.c)では、ユーザーの見張りの数を増やせないときに、inotify がこのコードを返しています。メッセージの後半の System limit for number of file watchers reached も、見張れる数の上限に届いたことを表しています。Vite の開発サーバーでは、同じメッセージが file watcher error: に続けて表示され、開発サーバーは動き続けました。

いま使っている数と上限を確かめる

上限は sysctl か /proc/sys/fs/inotify/max_user_watches で確かめられます。

text
$ sysctl fs.inotify.max_user_watches fs.inotify.max_user_instances
fs.inotify.max_user_watches = 128415
fs.inotify.max_user_instances = 128

この上限は、ユーザーごとの数です。先ほどの Linux 6.18 のソースでは、既定値をマシンのメモリーの1%から計算し、8192 から 1048576 の間に収めています。メモリーが少ないマシンほど、既定値は小さくなります。

どのプロセスがいくつ使っているかは、/proc/<プロセス番号>/fdinfo/ の中身で分かります。カーネルのドキュメントの /proc の説明には、inotify のファイルディスクリプターの fdinfo に、見張りごとに出る inotify wd:… の形の行の例があります。次の count-watches.sh は、この行を数えて、多い順に表示します。

bash
# inotify の見張りを使っているプロセスと、その数を多い順に表示する
for fd in /proc/[0-9]*/fdinfo/*; do
  n=$(grep -c '^inotify' "$fd" 2>/dev/null) || continue
  [ "$n" -gt 0 ] || continue
  pid=${fd#/proc/}; pid=${pid%%/*}
  echo "$n $pid $(tr '\0' ' ' < /proc/$pid/cmdline | cut -c1-60)"
done | sort -rn | head -5

上限を十分に上げてから検証用のプロジェクトで Vite を起動し、このスクリプトの1行目を見ると、Vite だけで 958 個使っていました(左から、数、プロセス番号、コマンドです)。

text
$ bash count-watches.sh | head -1
958 5014 node /path/to/app/node_modules/.bin/vite --port 5173

検証用のプロジェクトのファイルは、package.json や検証用のスクリプトも含め、node_modules/ の中を除いて910個でした。フォルダーはプロジェクトのフォルダー自身を含めて48個で、その合計(958)と同じ数でした。上限はユーザーごとなので、同じユーザーで動いているほかのプロセスの分も合わせて数えられます。

上限を上げて直す

Vite の公式ドキュメントのトラブルシューティングでは、524288 に上げる例が載っています。sysctl で値を変えると、その場で効きます。

text
$ sudo sysctl fs.inotify.max_user_watches=524288
fs.inotify.max_user_watches = 524288

この状態で開発サーバーを起動し直すと、ENOSPC の行は1行も出なくなりました。ブラウザでページを開いたまま src/dir40/m1.js を書き換えると、Vite がそれを検知してページを読み込み直し、見出しは v1 = 100 に変わりました。

text
$ npx vite --port 5173

  VITE v8.3.8  ready in 166 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
11:06:54 PM [vite] (client) page reload src/dir40/m1.js
(以下省略)

sysctl で変えた値は、マシンを再起動すると元に戻ります。再起動のあとも残すには、/etc/sysctl.d/ に設定ファイルを置きます。systemd の sysctl.d の説明のとおり、このフォルダーの .conf ファイルは起動のときに読み込まれます。ファイルの名前は、末尾を .conf にします。

text
$ echo 'fs.inotify.max_user_watches=524288' | sudo tee /etc/sysctl.d/99-inotify-watches.conf
fs.inotify.max_user_watches=524288
$ sudo sysctl --system
(省略)
* Applying /etc/sysctl.d/99-inotify-watches.conf ...
(省略)
fs.inotify.max_user_watches = 524288

sudo sysctl --system は、システムの設定ファイルのフォルダーから値をすべて読み込み直すコマンドです。上限を 100 に下げた状態から実行して、ファイルの値(524288)に変わることを確かめました。出力にはほかの設定ファイルの行も並ぶので、関係する行だけを残しています。

見張るファイルを減らして直す

上限を変える権限がないときや、テストのデータや画像など、開発中に書き換えないファイルが大量にあるときは、それらを見張る対象から外す方法もあります。Vite では、公式ドキュメントの server.watch に、ファイルを見張るライブラリ(chokidar)の設定を書けます。.git/ や node_modules/ は、もともと見張りの対象から外れています。

上限を 600 にして(ファイルとフォルダーを全部見張るには足りない数です)、まず設定なしで起動すると、ENOSPC の行が 365 行出て、src/dir40/m1.js を書き換えても画面は変わりませんでした。そこで、次の vite.config.js を置いて、fixtures/ を外しました。

js
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    watch: {
      // 開発中に書き換えないフォルダーを、見張る対象から外す
      ignored: ['**/fixtures/**'],
    },
  },
});

同じ上限 600 のまま起動し直すと、ENOSPC の行は出なくなり、src/dir40/m1.js を書き換えると見出しが v1 = 100 に変わりました。外すのは、開発中に中身を書き換えないフォルダーだけにします。

​Posted by 86