Tình huống gặp lỗi

Bạn mở VS Code trên máy Linux — một monorepo Node.js, một ứng dụng React ngập trong node_modules, hoặc chỉ là một workspace lớn — và thấy thông báo này:

Error: ENOSPC: System limit for number of file watchers reached, watch '/home/user/project/src'

VS Code dừng theo dõi thay đổi file. ESLint ngừng phản hồi. TypeScript mất dấu các chỉnh sửa. Live reload im lặng. Đôi khi trình soạn thảo chỉ chạy chậm mà không hiện lỗi gì cả.

Nguyên nhân thực sự

Linux dùng inotify để theo dõi thay đổi của file. Kernel giới hạn số lượng file watch mà một người dùng có thể nắm giữ — mặc định là 8192. VS Code cùng các extension (ESLint, TypeScript server, Prettier) cộng thêm các build tool như webpack hay Vite có thể ngốn hết con số đó trên một dự án vừa phải một cách dễ dàng.

Kiểm tra giới hạn hiện tại của bạn:

cat /proc/sys/fs/inotify/max_user_watches

Nếu hiển thị 8192 — hoặc bất kỳ giá trị nào dưới 65536 — thì đó chính là thủ phạm.

Cũng kiểm tra giới hạn inotify instance (khác với watches):

cat /proc/sys/fs/inotify/max_user_instances

Mặc định là 128. Giá trị thấp ở đây có thể gây ra một dạng lỗi tương tự.

Sửa nhanh (cho đến khi khởi động lại)

Tăng giới hạn ngay lập tức mà không cần chỉnh sửa file config nào:

sudo sysctl fs.inotify.max_user_watches=524288

Kernel áp dụng ngay lập tức. Sau đó khởi động lại VS Code — cần khởi động mới để nhận các watch slot vừa được cấp. Dùng cách này để kiểm tra nhanh; giới hạn sẽ về mặc định sau khi reboot.

Sửa vĩnh viễn

Có hai lựa chọn. Chọn cái phù hợp với thiết lập của bạn.

Cách A — Chỉnh sửa trực tiếp sysctl.conf

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Cách B — Tạo file config riêng (khuyến nghị)

echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/60-vscode-watches.conf
sudo sysctl --system

Một file riêng trong sysctl.d/ giúp thay đổi được tách biệt. Dễ theo dõi, dễ xóa khi cần.

Kiểm tra sau khi sửa

Xác nhận giá trị mới đã được áp dụng:

cat /proc/sys/fs/inotify/max_user_watches
# Kết quả hiển thị: 524288

Khởi động lại VS Code và mở lại dự án. Lỗi biến mất. Các extension hoạt động trở lại — TypeScript nhận thay đổi, ESLint highlight theo thời gian thực, live reload hoạt động bình thường.

Muốn chắc chắn cài đặt vẫn còn sau khi reboot?

sudo reboot
# Sau khi đăng nhập:
cat /proc/sys/fs/inotify/max_user_watches

Vẫn là 524288? Vậy là xong.

Tại sao là 524288?

Đó là con số mà tài liệu cài đặt Linux chính thức của VS Code khuyến nghị. Với hầu hết các dự án — kể cả monorepo lớn — con số này là quá đủ. Trên server bị giới hạn RAM, 65536 hoặc 131072 là mức thỏa hiệp hợp lý.

Mỗi inotify watch chiếm khoảng 1 KB bộ nhớ kernel. Vậy 524288 watches = ~512 MB trong trường hợp xấu nhất. Trên thực tế, một máy dev đang hoạt động với VS Code + Node.js + webpack có thể dùng từ 50.000 đến 100.000 watches. Bạn sẽ không chạm đến trần.

Vẫn còn lỗi?

Đã tăng giới hạn mà vẫn báo lỗi? Một số điều cần kiểm tra thêm:

Loại trừ node_modules trong VS Code — mở Settings và thêm vào files.watcherExclude:

"files.watcherExclude": { "/node_modules/": true, "/.git/": true, "/dist/": true }

    Chỉ riêng bước này có thể giảm số watch đi hàng chục nghìn.
  
  - **Tăng `max_user_instances` cùng lúc** — nếu giá trị đó cũng thấp, thêm vào file config tương tự:
    ```
echo fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.d/60-vscode-watches.conf
sudo sysctl --system

Nhiều cửa sổ VS Code + extension — mỗi cửa sổ mở tạo ra một bộ watcher riêng. Đóng những cửa sổ không dùng đến.
Các công cụ khác cũng dùng watch — Dropbox, Syncthing, và webpack dev server đều dùng inotify. Tìm xem ai đang tiêu thụ nhiều nhất:

Đếm tổng số inotify watch đang hoạt động:

cat /proc//fdinfo/ 2>/dev/null | grep -c inotify

Xem process nào đang dùng chúng:

find /proc/*/fd -lname anon_inode:inotify 2>/dev/null |
cut -d/ -f3 | xargs -I{} ps -p {} -o comm= 2>/dev/null |
sort | uniq -c | sort -rn | head -20

  

## Lưu ý cho người dùng WSL2
Đang dùng VS Code qua Remote-WSL và gặp lỗi này? Cách sửa hoàn toàn giống nhau — chạy lệnh `sysctl` bên trong shell Linux của WSL2, không phải trong Windows PowerShell. Giới hạn inotify là cài đặt của Linux kernel; Windows không có khái niệm này.

Sửa lỗi "ENOSPC: System limit for number of file watchers reached" trên VS Code (Linux)