검증 환경

본 절은 원문 사례·문서에 등장한 버전/도구를 정리한 것이다. 별도 실험실 재현이 명시되지 않은 항목은 일반화하지 않는다.

항목본문·원문에서 확인된 범위
런타임/도구Linux
문서 정리일2026-08-26
  • OS/CI 세부 값은 프로젝트마다 다르므로, 적용 전 로컬에서 동일 오류 메시지를 재확인한다.

문제 정의

운영 중인 Node.js 서버에서 파일을 업로드하는 도중 프로세스가 비정상 종료되며 아래 에러가 발생했다.

1

Error: ENOSPC

파일 업로드가 시작되면 Node.js 프로세스가 크래시하고, 이후 서버 코드가 더 이상 동작하지 않는다.

이때 서버 디스크 상태를 확인한 결과는 아래와 같았다.

1
2
3
4
5
6
7
8
9

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/xvda1      7.9G  4.1G  3.5G   55% /
udev            288M  8.0K  288M    1% /dev
tmpfs           119M  168K  118M    1% /run
none            5.0M     0  5.0M    0% /run/lock
none            296M     0  296M    0% /run/shm
/dev/xvdf       9.9G  3.0G  6.5G   32% /vol
overflow        1.0M  1.0M     0  100% /tmp

보이는 것처럼 루트(/)는 55%, /vol은 32%를 사용 중이다. 즉 단순히 “디스크가 가득 찼다"고 보기 어려운 상황이며, 이 때문에 원인을 하나로 단정하지 말고 순서대로 점검해야 한다.

증상 fingerprint

항목값
에러 메시지Error: ENOSPC (errno 28, “No space left on device”)
발생 단계파일 업로드가 실제로 시작되는 시점
관련 런타임Node.js on Linux
흔한 오해“무조건 디스크가 가득 찼다"고 단정하는 것
빠른 판단 기준df -h로 여유 공간이 나오는데도 ENOSPC가 발생하면 디스크 용량 외 원인을 의심

원인 탐구 — 빠른 진단 체크리스트

ENOSPC 에러가 나면 아래 항목을 순서대로 확인해 어느 원인이 맞는지 좁혀 나가야 한다.

  • 실제 디스크 공간이 남아 있는가 → df -h (루트 뿐 아니라 /tmp, /vol 등 마운트 전부 확인)
  • 남은 inode가 부족하지 않은가 → df -i
  • 업로드가 쓰는 임시 경로(/tmp)가 가득 차지 않았는가 → df -h
  • Node.js가 inotify(파일 감시)를 사용하는가
  • inotify 최대 감시 한도는 얼마인가 → sysctl fs.inotify.max_user_watches

이 중 “디스크 공간은 남아 있는데도 에러가 나는” 상황에서는 마지막 두 항목, 즉 inotify 감시 수 한도 초과가 흔한 원인이 된다.

근본 원인 분석 — 원인 후보 매트릭스

같은 ENOSPC 메시지라도 원인은 여러 가지일 수 있다. 상황별로 무엇을 확인하고 어떻게 풀어갈지 정리하면 아래와 같다.

원인 후보확인 명령해당할 때의 증상해결 방향
실제 디스크 공간 부족df -h해당 마운트의 Avail이 0에 수렴불필요한 파일 정리, 파티션 증설
inode 부족df -iIUse%가 100%에 근접소형 파일 정리
임시 마운트(/tmp) 가득df -h해당 경로의 Use%가 100%임시 파일 삭제, 정리 스케줄
inotify 감시 한도 초과sysctl fs.inotify.max_user_watches디스크 여유는 있는데 ENOSPC, Node.js 크래시아래의 sysctl 한도 확대 설정
열린 파일 디스크립터 부족ulimit -H파일 핸들러를 다량 사용하는 작업에서 발생파일 핸들러 사용 줄이기, fs.file-max 조정

이 매트릭스에서 디스크가 남아 있는데도 ENOSPC가 나는 케이스는 크게 두 원인 중 하나로 좁혀진다. 그리고 실제 문의에서 채택된 해결책은 inotify 감시 한도 확장이다.

코드 해결책 — 해결 방법

아래 명령은 inotify 최대 감시(watch) 수를 늘리면서, 재부팅 이후에도 유지되도록 시스템 설정 파일에 기록한다.

(대부분 Linux 배포판, 기존 /etc/sysctl.conf 방식):

1
2

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

(Arch Linux 계열, /etc/sysctl.d/ 방식):

1
2

echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.d/99-sysctl.conf
sysctl --system

sysctl -p 또는 sysctl --system은 변경 사항을 즉시 커널에 반영한다. 이 값이 설정 파일에 저장되어 있기 때문에 시스템을 재시작해도 유지된다는 점이 정리 포인트다.

잘못된 해결책

  • 프로세스만 재시작하고 끝내는 것 — inotify 감시 수가 커지는 상황이 계속되면 동일 에러가 반복된다. 한도 자체를 조정해야 한다.
  • max_user_watches를 무한대로 설정하는 것 — 보통 큰 값이 필요하지만, 과도하게 올리면 커널 메모리 사용량이 늘고 다른 서비스의 안정성과 경쟁할 수 있다. 상황에 맞는 적정값을 쓰는 것이 바람직하다. (환경에 따라 다를 수 있음)

검증 명령

설정이 실제로 반영되었는지 아래 명령으로 확인한다.

1

sysctl fs.inotify.max_user_watches

화면에 524288이 출력되면 성공이다. 그리고 실제 파일 업로드를 다시 수행하여 Node.js 프로세스가 크래시하지 않는지 확인하는 것이 최종 검증이다.

프로세스가 살아 있는지도 확인할 수 있다.

1

ps aux | grep node

향후 예방 조치 — 재발 방지 체크

  1. df -h, df -i 사용률을 주기적으로 확인하고 임계값 알림을 설정한다.
  2. /tmp 등 업로드 임시 경로가 급격히 가득 차지 않도록 주기적 정리 작업을 배치한다.
  3. inotify를 과도하게 사용하는 파일 감시기가 이 서버에 추가되지 않도록 관리한다.
  4. sysctl 변경은 반드시 배포/재시작 후에도 유지되는지 점검한다.

DevTrace verdict

이 문제의 핵심은 디스크가 가득 찬 것이 아니라, Node.js 파일 업로드 환경에서 inotify 감시(watch) 한도 초과로 같은 ENOSPC 에러가 발생할 수 있다는 점이며, fs.inotify.max_user_watches 값을 sysctl로 영구 반영하는 것이 채택 해결책이다.

DevTrace 결론

ENOSPC는 표면적으로 ‘디스크 공간 부족’처럼 보이지만, Node.js 파일 업로드 맥락에서는 inotify 감시 한도 초과가 흔한 원인이며 fs.inotify.max_user_watches를 sysctl로 영구 반영하는 것이 근본 해결책이다.

원문 출처는 문제 발견의 단서이며, 위 판단과 점검 항목은 DevTrace의 독자 분석이다.

출처: https://stackoverflow.com/questions/22475849/node-js-what-is-enospc-error-and-how-to-solve