리눅스(Linux) 환경이나 WSL, Docker 컨테이너 안에서 Node.js, React, Vite 프로젝트 개발 서버를 띄워두고 작업하다가 갑자기 Error: ENOSPC: System limit for number of file watchers reached 에러와 함께 서버가 종료되는 현상을 경험해봤을 것이다. 다만 커널 레벨의 인노티파이(inotify) 제한 값과 이 에러의 정확한 원인을 모른 채 개발 서버만 계속 재시작하는 경우가 많다. 이번에는 이 에러가 정확히 왜 발생하며, 시스템의 파일 워처 제한을 늘려 문제를 근본적으로 해결하는 방법을 완벽하게 정리해서 소개하겠다.
에러 메시지에 포함된 ENOSPC는 Error No Space의 약어다. 디스크 용량이 부족할 때도 발생하지만, 파일 감시 시스템에서는 커널이 할당할 수 있는 파일 워처(File Watcher) 공간이 부족하다는 의미로 쓰인다.
리눅스 커널은 파일 시스템의 변경 사항을 실시간으로 감지하기 위해 inotify라는 서브시스템을 활용한다. Vite, Webpack, Nodemon 같은 개발 도구와 VSCode 등의 IDE는 개발자가 코드를 수정할 때 이를 즉시 감지하여 핫 리로딩(HMR)을 수행하기 위해 프로젝트 내 수많은 파일에 inotify 감시자를 등록한다. 문제는 주요 리눅스 배포판의 기본 inotify 파일 감시 수 제한이 지나치게 낮게 설정되어 있다는 점이다.
리눅스 커널은 /proc/sys/fs/inotify/ 경로 아래의 파일들을 통해 inotify 동작 한계를 제어한다. 각 설정값의 역할은 다음과 같다.
| 파라미터 항목 | 기본값 (일반적인 Linux) | 설명 |
|---|---|---|
| max_user_watches | 8192 | 한 사용자의 프로세스가 감시(Watch)할 수 있는 최대 디렉토리 및 파일 개수 |
| max_user_instances | 128 | 한 사용자가 생성할 수 있는 최대 inotify 인스턴스 개수 |
| max_queued_events | 16384 | inotify 이벤트 큐에 담길 수 있는 최대 이벤트 개수 |
대부분의 현대 웹 프로젝트는 node_modules 폴더 내부에만 수만 개의 파일이 존재한다. 기본값인 8,192개로는 대형 프론트엔드나 백엔드 프로젝트 하나만 실행해도 한계를 쉽게 초과하게 된다.
현재 시스템에 설정된 최대 파일 워처 수를 확인하는 방법은 간단하다. 터미널에서 proc 파일 시스템을 읽거나 sysctl 명령어를 실행하면 된다.
cat /proc/sys/fs/inotify/max_user_watches
# 또는
sysctl fs.inotify.max_user_watches출력 결과가 8192 또는 16384 정도로 낮다면, 이 값을 대폭 늘려주어야 대규모 프로젝트 개발 시 에러가 발생하지 않는다.
현재 열려 있는 세션에서 바로 에러를 해결하고 싶다면 sysctl 명령으로 즉시 값을 변경할 수 있다. 524,288(512k) 정도로 설정하면 대규모 모노레포 환경에서도 부족함 없이 작동한다.
sudo sysctl fs.inotify.max_user_watches=524288이 방식은 서버를 재부팅하면 다시 기본값으로 원상복구되는 단점이 있다.
시스템이 재부팅되어도 계속 수정된 한계치를 유지하려면 /etc/sysctl.conf 파일이나 /etc/sysctl.d/ 환경에 설정 값을 등록해야 한다.
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -psysctl -p 명령을 실행하면 재부팅 없이 변경된 파일의 설정을 시스템 커널에 즉시 반영한다.
실무 환경에서 흔히 범하는 잘못된 대응과 올바른 설정 적용법을 코드로 비교해보자.
✗ 원인을 몰라 node_modules를 삭제하고 다시 설치하거나 프로젝트 세팅만 수정하는 경우다. 커널 제한 문제이므로 노드 패키지를 재설치해도 문제는 해결되지 않는다.
# ✗ 잘못된 방식: 패키지를 다시 설치해도 커널 제한은 그대로다.
rm -rf node_modules
npm install
npm run dev
# 여전히 동일한 ENOSPC 에러 발생
✓ sysctl 설정을 영구적으로 수정하고 커널 파라미터를 새로고침한 뒤 개발 서버를 재실행한다.
# ✓ 올바른 방식: 커널의 inotify 감시 한계 자체를 늘려준다.
echo "fs.inotify.max_user_watches=524288" | sudo tee /etc/sysctl.d/99-max-user-watches.conf
sudo sysctl --system
# 설정 적용 확인
cat /proc/sys/fs/inotify/max_user_watches
# 출력값: 524288설정이 성공적으로 적용된 후 개발 서버(npm run dev 등)를 실행하면 더 이상 ENOSPC 에러가 발생하지 않고 파일 감시가 정상 작동한다.
파일 워처 값을 변경할 때 백엔드 및 DevOps 관점에서 고려해야 할 사항들이 있다.
첫째, Docker 및 WSL2 환경에서의 설정이다. Docker 컨테이너 내부에서 sysctl을 변경하려 하면 권한 오류(Read-only file system)가 발생한다. inotify 파라미터는 호스트 OS의 커널 자원을 공유하므로, 컨테이너 내부가 아닌 Docker가 동작 중인 리눅스 호스트 서버(또는 Windows WSL2 가상머신) 본체에서 sysctl 설정을 변경해야 한다.
둘째, 메모리 사용량에 대한 오해다. max_user_watches를 524,288로 높이면 메모리를 엄청나게 먹지 않을까 걱정하는 경우가 있다. 64비트 시스템 기준으로 파일 감시자 1개당 약 1KB 미만의 커널 메모리를 사용한다. 50만 개를 확보하더라도 최대 할당 메모리는 수백 MB 수준이며, 실제로 감시 중인 파일 개수에 비례해서만 소모되므로 일반적인 개발 서버 자원 관리에 아무런 부담을 주지 않는다.
Linux ENOSPC 에러 해결은 커널의 파일 감시 한계를 제대로 이해하고 최적의 환경을 구축하는 첫걸음이다. 소소해 보이는 개발 환경 설정 하나가 모여서 백엔드와 프론트엔드 빌드 프로세스의 생산성을 크게 높인다는 점을 잊지 말자. 이 글의 sysctl 영구 적용 방법을 참고해 설정을 마치면, 더 이상 파일 워처 제한으로 개발 서버가 끊기는 일 없이 안정적인 개발 환경을 구축할 수 있을 것이다.