ENOSPC: System limit for number of file watchers reached 해결 방법, 디스크는 비었는데 no space라고 한 이유
문제 발생
새 노트북에 프로젝트를 받아 개발 서버를 띄웠더니 바로 죽었습니다.
Error: ENOSPC: System limit for number of file watchers reached, watch '/home/me/app/src'
at FSWatcher.<computed> (node:internal/fs/watchers:247:19)
at Object.watch (node:fs:2418:36)ENOSPC라는 글자를 보고 제일 먼저 디스크를 봤습니다. 디스크는 70% 넘게 비어 있었습니다. 용량이 남았는데 "no space"라고 하는 겁니다.
더 이상했던 건 다음 날이었습니다. 개발 서버가 멀쩡히 떴고 에러도 없었는데, 어떤 폴더의 파일을 고치면 핫 리로드가 되고 어떤 폴더는 아무 반응이 없었습니다. 저장을 두 번 해도, 세 번 해도 조용했습니다. 에러 로그가 한 줄도 없으니 어디부터 봐야 할지 알 수 없었습니다.
이 글은 Node 22.23과 Linux에서 재현했습니다. 재현 환경의 max_user_watches는 기본값인 63968이었고, 한도를 바꾸지 않은 상태에서 측정한 숫자들입니다.
원인 분석
이 ENOSPC는 디스크가 아니라 inotify 한도입니다. Linux에서 파일 변경 감지는 커널의 inotify를 씁니다. inotify(7) 매뉴얼은 /proc/sys/fs/inotify/ 아래 값들을 "inotify가 소비하는 커널 메모리를 제한하는 데 쓰이는 인터페이스"라고 소개하면서, max_user_watches를 실제 사용자 ID당 만들 수 있는 watch 개수의 상한이라고 설명합니다. 이 한도를 넘으면 watch를 더 등록할 수 없고, Node는 그 실패를 ENOSPC로 전달합니다. 메시지의 "space"는 디스크 공간이 아니라 watch 자리입니다.
재현해 보니 정확히 한도에서 멈췄습니다. 파일 7만 개를 하나씩 감시하게 해 봤습니다.
현재 한도: 63968
감시 개수: 63961
ENOSPC: System limit for number of file watchers reached, watch '.../f63961'
errno=-28 syscall=watch디렉터리 감시는 재귀적이지 않습니다. 그래서 하위 폴더마다 watch가 하나씩 듭니다. 매뉴얼이 한계와 주의사항에서 분명히 적습니다. 디렉터리에 대한 inotify 감시는 재귀적이지 않으므로, 하위 디렉터리를 감시하려면 추가 watch를 만들어야 한다고요. 감시는 경로가 아니라 inode 단위라는 설명도 함께 있습니다. 폴더 500개에 하위 폴더까지 1501개인 트리를 recursive: true로 한 번 감시해 보니, watch가 정확히 1501개 등록됐습니다. 코드 한 줄이 watch 1501개를 쓴 겁니다.
프로세스가 실제로 몇 개의 watch를 쥐고 있는지는 /proc/<pid>/fdinfo에서 셀 수 있습니다.
$ cat /proc/<pid>/fdinfo/* 2>/dev/null | grep -c '^inotify '그리고 node_modules가 그 자리를 거의 다 먹습니다. 패키지 507개가 들어 있는 node_modules를 재귀로 한 번 감시해 보니 이렇게 나왔습니다.
디렉터리 3161개 + 파일 39923개 = watch 43084개디렉터리 수와 파일 수의 합과 watch 수가 정확히 일치했습니다. Node의 재귀 감시는 Linux에서 폴더만이 아니라 파일 하나하나에도 watch를 거는 셈입니다. 한도가 63968이니, node_modules 하나를 감시하는 것만으로 전체의 **67%**를 써 버립니다. 반대로 같은 프로젝트의 소스 폴더(하위 폴더 41개, 파일 320개)만 감시했을 때는 361개였습니다. 쓸 자리를 다 쓰게 만든 쪽은 내가 고치는 파일들이 아니라 손도 안 대는 의존성 폴더였습니다.
한도는 프로세스당이 아니라 사용자당입니다. 매뉴얼의 문장이 "사용자 ID당"인 게 중요합니다. 편집기, 개발 서버 두 개, 테스트 러너, tail -f가 같은 통장을 씁니다. 그래서 "어제는 됐는데 오늘은 안 되는" 일이 생깁니다. 같은 node_modules를 두 프로세스가 각각 감시하게 해 보니 이렇게 갈렸습니다.
[1번] 실제 등록된 watch: 43084
[2번] 실제 등록된 watch: 20877 ← 합계 63961, 한도 63968여기서 두 번째 증상의 답이 나왔습니다. 2번은 에러를 내지 않았습니다. 예외도, error 이벤트도 없었습니다. 그냥 트리의 절반만 감시하고 나머지는 조용히 포기했습니다. 감시가 걸린 폴더를 고치면 핫 리로드가 되고, 못 걸린 폴더를 고치면 아무 일도 일어나지 않습니다. 한도에 부딪혔을 때 운이 좋으면 ENOSPC로 터지고, 운이 나쁘면 아무 말 없이 절반만 동작합니다. 뒤쪽이 훨씬 찾기 어렵습니다.
해결 방안
- 먼저 한도와 지금 쓰는 양을 확인합니다. 추측으로 설정을 바꾸기 전에 두 숫자를 봅니다.
$ cat /proc/sys/fs/inotify/max_user_watches
63968
$ cat /proc/[0-9]*/fdinfo/* 2>/dev/null | grep -c '^inotify '
43091어느 프로세스가 쓰고 있는지까지 보려면 프로세스별로 셉니다. 범인이 바로 드러납니다.
for p in /proc/[0-9]*; do
n=$(cat $p/fdinfo/* 2>/dev/null | grep -c '^inotify ')
[ "$n" -gt 0 ] && echo "$n ${p#/proc/} $(tr -d '\0' < $p/cmdline | cut -c1-40)"
done | sort -rn | head재현 환경에서 돌리니 43084 하나가 전체의 거의 전부였습니다. 편집기를 여러 개 띄워 둔 상태라면 여기서 몇 천 개씩 쓰고 있는 프로세스가 같이 나옵니다. 쓰지 않는 창을 닫는 것만으로 해결되는 경우도 있습니다.
- 한도를 올립니다. 다만 근본 해결은 아닙니다. 검색하면 가장 먼저 나오는 방법이고, 실제로 즉효입니다. webpack 문서의 "Not Enough Watchers" 항목도
cat /proc/sys/fs/inotify/max_user_watches를 확인해 보라고 안내합니다. 값이 작으면 감시가 변경을 인식하지 못한다고요.
$ sudo sysctl fs.inotify.max_user_watches=524288재부팅 후에도 유지하려면 설정 파일에 적어 둡니다.
$ echo 'fs.inotify.max_user_watches=524288' | sudo tee /etc/sysctl.d/60-inotify.conf
$ sudo sysctl --system매뉴얼이 이 값들을 "커널 메모리를 제한하는 인터페이스"라고 설명한다는 걸 기억해 둘 만합니다. 한도는 메모리를 아끼기 위해 있는 것이라, 무한정 올리는 건 공짜가 아닙니다. 그리고 컨테이너 안에서는 이 값이 호스트 커널의 값이라 컨테이너에서 바꿀 수 없는 경우가 많습니다. 그때는 호스트에서 바꾸거나 3번으로 갑니다. 이 글의 재현은 한도를 바꾸지 않은 상태로 진행했습니다.
- 감시 대상에서
node_modules를 뺍니다. 효과가 가장 큽니다. 위에서 본 대로 watch의 99%가 안 고치는 폴더에 쓰이고 있었습니다. Vite는 기본적으로 이걸 해 줍니다. 공식 문서에 따르면 Vite의 감시자는 루트를 감시하면서.git/,node_modules/,test-results/, 그리고 Vite의 캐시·빌드 출력 디렉터리를 기본으로 건너뜁니다. 그러니 Vite를 쓰면서 이 에러가 난다면server.watch에 직접 넣은 설정이나 다른 감시자(테스트 러너, 별도 스크립트)를 먼저 의심하는 게 맞습니다.
webpack은 직접 적습니다. 문서가 큰 폴더를 정규식으로 제외하는 예시를 그대로 보여 줍니다.
module.exports = {
watchOptions: {
ignored: /node_modules/,
},
};직접 fs.watch를 쓰는 스크립트라면 트리 전체를 재귀로 걸지 말고 필요한 폴더만 겁니다. 소스만 감시하면 361개로 끝난다는 걸 위에서 확인했습니다.
- Docker, WSL, 네트워크 볼륨에서는 폴링을 고려합니다. 마운트된 파일시스템에서는 inotify 이벤트가 아예 전달되지 않는 경우가 있습니다. 한도를 올려도 감지가 안 되는 상황입니다. webpack 문서가 이 경우를 직접 언급합니다. 감시가 동작하지 않으면 폴링을 시도해 보라고 하면서, NFS나 VirtualBox, WSL, 컨테이너, Docker에서 생기는 문제에 도움이 될 수 있다고요. 이어서 그런 경우에는 폴링 간격을 주고
/node_modules/같은 큰 폴더를 제외해 CPU 사용량을 최소로 유지하라고 덧붙입니다.
watchOptions: { poll: 1000, ignored: /node_modules/ }Vite에서는 server.watch가 chokidar로 전달되는 옵션이라 usePolling을 켤 수 있습니다. 단 문서가 WSL2 항목에서 usePolling은 CPU 사용률을 높인다고 못 박아 두었으니, 배터리로 쓰는 노트북에서는 체감이 꽤 큽니다. 폴링은 inotify가 통하지 않을 때의 차선책으로 두는 게 맞습니다.
- 에러가 없다고 정상이 아닙니다. 이번 사고에서 제일 오래 헤맨 부분입니다. 핫 리로드가 일부 폴더에서만 안 되거나, 테스트가 변경을 못 잡거나, 저장해도 빌드가 안 돌면 로그를 더 찾기 전에 watch 수를 세어 보는 게 빠릅니다. 1번의 명령 두 줄이면 됩니다. 합계가 한도에 붙어 있으면 그게 원인입니다. 개발 서버와 편집기를 다시 띄우면 일단 풀리지만, 같은 상태가 반복된다면 3번으로 감시 대상을 줄여야 합니다.
덧붙여, 감시자가 많은 프로젝트에서는 watch를 쓰고 닫지 않는 코드도 같이 봐야 합니다. fs.watch로 만든 감시자는 close()를 호출해야 watch가 반환됩니다. 파일을 열 때마다 감시자를 새로 만들고 닫지 않는 코드가 있으면 시간이 지날수록 한도에 가까워지고, 결국 "오래 켜 두면 핫 리로드가 멈추는" 증상이 됩니다.
댓글0
아직 댓글이 없어요. 첫 댓글을 남겨 보세요.
댓글을 남기려면 로그인이 필요해요. 로그인