[카테고리:] 정보

리눅스 서버에서 Command Not Found 오류가 발생할 때 해결 방법

리눅스 서버에 SSH로 접속해 평소 사용하던 명령어를 실행했는데 갑자기 Command Not Found 오류가 나타난 경험이 있으신가요? 특히 Python이나 Node.js를 설치한 직후, 서버를 재부팅한 뒤, 또는 일반 사용자에서는 실행되던 명령어가 sudo나 Cron 환경에서 실행되지 않을 때 이런 문제가 발생할 수 있습니다.

명령어를 분명 설치했는데도 bash: command not found라는 메시지가 나오면 프로그램이 제대로 설치되지 않았다고 생각하기 쉽습니다. 하지만 실제로는 PATH 환경변수에 실행 파일 경로가 등록되지 않았거나, 현재 셸과 실행 환경이 달라 명령어를 찾지 못하는 경우도 많습니다.

이때 프로그램을 무작정 다시 설치하거나 인터넷에서 찾은 PATH 설정을 그대로 복사하면 기존 환경변수를 덮어쓰거나 잘못된 실행 파일을 사용하게 될 수 있습니다. 따라서 먼저 명령어가 실제로 존재하는지, 현재 셸이 어떤 경로에서 실행 파일을 찾는지 구분해서 확인하는 것이 중요합니다.

이번 글에서는 command -v, type, echo $PATH, find 등의 명령어로 오류 원인을 추적하고, 패키지 설치, PATH 수정, 실행 권한, sudo·Cron 환경 차이, 셸 설정 문제까지 실제 서버 점검 순서대로 해결하는 방법을 살펴봅니다.

Command Not Found 핵심 명령어 한눈에 보기

명령어가 실행되지 않는다면 먼저 아래 점검 명령어를 사용하세요. 예제에서는 node 명령어를 기준으로 설명합니다.

점검 목적	명령어
명령어 검색	`command -v node`
명령어 종류 확인	`type -a node`
PATH 확인	`printf '%s\n' "$PATH"`
실행 파일 검색	`find /usr/local /opt -type f -name node 2>/dev/null`
실행 권한 확인	`ls -l /usr/local/bin/node`
sudo 환경 PATH 확인	`sudo env \| grep '^PATH='`

command -v로 명령어를 찾지 못한다고 해서 프로그램이 반드시 설치되지 않은 것은 아닙니다. 설치된 실행 파일이 PATH에 포함되지 않았거나 현재 셸 환경에서 접근할 수 없는 상태일 수도 있습니다.

리눅스 Command Not Found 오류와 PATH 환경변수 점검 화면 — Command Not Found 오류 발생 시 command -v와 PATH 환경변수를 확인해 명령어를 찾지 못하는 원인을 점검하는 예시입니다.

1. Command Not Found 오류가 발생하는 대표적인 원인

리눅스에서 명령어를 입력하면 셸은 내장 명령어, 함수, 별칭 및 PATH에 등록된 경로 등을 확인해 실행할 대상을 찾습니다.

이 과정에서 실행할 명령어를 찾지 못하면 셸에 따라 다음과 같은 오류가 표시될 수 있습니다.

$ node --version
bash: node: command not found

대표적인 원인은 다음과 같습니다.

패키지 미설치: 실행하려는 프로그램이 서버에 설치되지 않은 경우
PATH 누락: 실행 파일이 있지만 PATH에 해당 디렉터리가 없는 경우
명령어 오타: 대소문자나 명령어 이름을 잘못 입력한 경우
사용자 환경 차이: SSH 사용자와 root 계정의 PATH가 다른 경우
셸 설정 문제: .bashrc, .profile 등의 환경변수 설정이 잘못된 경우
가상환경 문제: Python venv 또는 Node.js 버전 관리 환경이 활성화되지 않은 경우
자동 실행 환경: Cron, systemd 등에서 PATH가 다르게 적용되는 경우

따라서 Command Not Found 오류는 단순히 패키지를 설치하는 것만으로 해결되지 않을 수 있습니다.

2. command -v와 type으로 명령어 설치 여부 확인하기

가장 먼저 확인할 것은 현재 셸이 해당 명령어를 찾을 수 있는지입니다.

command -v node

정상적으로 찾을 수 있다면 다음과 같은 경로가 표시될 수 있습니다.

/usr/bin/node

아무 결과도 나타나지 않는다면 현재 환경에서 해당 명령어를 찾지 못하고 있다는 의미입니다.

명령어가 별칭인지, 셸 함수인지, 실행 파일인지까지 확인하려면 다음 명령어를 사용합니다.

type -a node

예를 들어 다음과 같은 결과가 나타날 수 있습니다.

node is /usr/local/bin/node
node is /usr/bin/node

이 경우 같은 이름의 실행 파일이 여러 위치에 존재한다는 것을 알 수 있습니다. 실제 실행되는 파일은 PATH 검색 순서와 셸 상태에 영향을 받습니다.

여러 버전의 Python이나 Node.js를 설치한 서버에서는 어떤 경로의 실행 파일이 우선 사용되는지 확인하는 것이 특히 중요합니다.

3. PATH 환경변수가 잘못됐는지 확인하기

명령어가 설치되어 있는데도 실행되지 않는다면 PATH 환경변수를 확인해야 합니다.

echo "$PATH"

일반적으로 다음과 같은 결과가 표시됩니다.

/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

PATH는 셸이 실행 파일을 검색하는 디렉터리 목록입니다. 각 경로는 콜론(:)으로 구분됩니다.

예를 들어 프로그램이 /opt/myapp/bin에 설치되어 있는데 해당 경로가 PATH에 없다면 명령어 이름만으로는 실행되지 않을 수 있습니다.

먼저 절대경로로 실행할 수 있는지 확인합니다.

/opt/myapp/bin/mytool --version

절대경로에서는 실행되지만 mytool만 입력하면 실패한다면 PATH 문제일 가능성이 높습니다.

현재 셸에서 임시로 경로를 추가하려면 다음과 같이 사용합니다.

export PATH="$PATH:/opt/myapp/bin"

다시 명령어를 확인합니다.

command -v mytool
mytool --version

이 설정은 현재 셸 세션에 적용됩니다. 새로운 로그인에서도 사용하려면 실제 셸 종류와 로그인 방식에 맞는 환경 설정 파일에 추가해야 합니다.

PATH를 수정할 때 기존 값을 제거하고 새 경로만 지정하면 ls, cp 같은 기본 명령어까지 찾지 못하는 문제가 발생할 수 있으므로 주의해야 합니다.

4. 프로그램이 설치되지 않았다면 패키지 관리자 확인하기

실행 파일을 찾을 수 없다면 패키지가 실제로 설치되어 있는지 확인합니다.

Ubuntu 또는 Debian 계열에서는 설치된 패키지를 다음과 같이 조회할 수 있습니다.

dpkg -l | grep -i curl

설치되지 않은 것이 확인됐고 해당 프로그램이 필요한 상황이라면 패키지 관리자를 통해 설치할 수 있습니다.

sudo apt update
sudo apt install curl

RHEL, Rocky Linux, AlmaLinux 등 DNF 기반 환경에서는 다음과 같은 방법을 사용할 수 있습니다.

sudo dnf install curl

다만 모든 프로그램이 배포판 기본 저장소에 존재하는 것은 아닙니다. Node.js, Python 또는 특정 개발 도구는 별도 저장소나 버전 관리 도구로 설치됐을 수 있으므로 기존 설치 방식을 먼저 확인하는 것이 좋습니다.

5. 실행 파일은 있는데 명령어가 실행되지 않는 경우

파일이 존재한다면 먼저 실행 권한과 파일 유형을 확인합니다.

ls -l /opt/myapp/bin/mytool
file /opt/myapp/bin/mytool

실행 권한이 없다면 일반적으로 Command Not Found보다는 Permission denied 같은 오류가 발생할 수 있습니다.

스크립트 파일의 경우 첫 줄에 지정된 인터프리터가 존재하지 않거나 줄바꿈 형식이 잘못되어도 실행이 실패할 수 있습니다.

head -n 1 /opt/myapp/bin/mytool

예를 들어 스크립트가 존재하지 않는 인터프리터를 참조한다면 파일 자체는 있어도 실행 과정에서 오류가 발생합니다.

또한 현재 디렉터리에 있는 실행 파일은 현재 디렉터리가 PATH에 포함되지 않았다면 이름만으로 실행되지 않을 수 있습니다.

./script.sh

이때는 실행 권한이 있어야 하며, 권한이 없다면 파일 소유자와 실행 목적을 확인한 뒤 필요한 권한만 부여해야 합니다.

6. sudo에서는 명령어가 실행되지 않는 이유

일반 사용자 계정에서는 정상적으로 실행되던 명령어가 sudo를 붙이면 찾을 수 없다는 오류를 표시하는 경우도 있습니다.

$ mytool --version
mytool 1.0

$ sudo mytool --version
sudo: mytool: command not found

이는 일반 사용자와 sudo 실행 환경의 PATH가 다르기 때문일 수 있습니다. 일부 시스템에서는 sudoers의 secure_path 설정이 명령어 검색 경로에 영향을 줍니다.

먼저 일반 사용자와 sudo 환경의 PATH를 비교합니다.

echo "$PATH"
sudo env | grep '^PATH='

실행 파일의 실제 위치도 확인합니다.

command -v mytool

필요하다면 신뢰할 수 있는 실행 파일의 절대경로를 지정해 실행할 수 있습니다.

sudo /opt/myapp/bin/mytool --version

다만 사용자별로 설치된 개발 도구를 root 권한으로 실행하면 파일 소유권이나 환경 설정이 달라질 수 있으므로 해당 프로그램에 관리자 권한이 실제로 필요한지 먼저 판단해야 합니다.

7. SSH에서는 되는데 Cron과 systemd에서는 실패하는 경우

SSH로 직접 로그인하면 정상적으로 실행되는 명령어가 Cron이나 systemd 서비스에서만 실패하는 경우가 있습니다.

이는 자동 실행 환경이 사용자의 로그인 셸과 동일한 환경변수를 불러오지 않을 수 있기 때문입니다.

Cron 작업에서는 실행 파일의 절대경로를 사용하는 것이 좋습니다.

/usr/bin/python3 /opt/scripts/backup.py

필요하다면 Crontab에 명시적으로 PATH를 지정할 수도 있습니다.

PATH=/usr/local/bin:/usr/bin:/bin

0 2 * * * /usr/bin/python3 /opt/scripts/backup.py

systemd 서비스라면 서비스 유닛의 ExecStart에 실행 파일의 절대경로를 지정하는 방식이 명확합니다.

ExecStart=/usr/bin/python3 /opt/scripts/backup.py

특히 Python 가상환경이나 Node.js 버전 관리 도구를 사용하는 경우 일반 셸에서만 설정되는 경로에 의존하지 않도록 구성해야 합니다.

8. .bashrc와 .profile 수정 후 명령어가 사라졌다면

환경변수 설정을 수정한 직후 기본 명령어까지 실행되지 않는다면 PATH가 잘못 덮어써졌는지 확인해야 합니다.

예를 들어 다음 설정은 기존 PATH를 제거합니다.

export PATH="/opt/myapp/bin"

이 경우 기본 명령어 디렉터리가 PATH에서 빠질 수 있습니다.

기존 경로를 유지하면서 추가하려면 다음처럼 작성합니다.

export PATH="$PATH:/opt/myapp/bin"

이미 PATH가 잘못 설정됐다면 현재 셸에서 임시로 기본 경로를 복구할 수 있습니다.

export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

그다음 실제로 잘못 수정한 .bashrc, .profile 등 환경 설정 파일을 확인하고 수정해야 합니다.

환경 설정 파일을 수정한 뒤에는 새 셸에서 테스트하는 것이 좋으며, 현재 SSH 세션을 바로 종료하지 않는 편이 안전합니다.

실전 점검 순서

예를 들어 서버에서 node 명령어가 실행되지 않는다면 다음 순서대로 확인할 수 있습니다.

# 1. 명령어 존재 여부 확인
command -v node

# 2. 명령어 종류와 경로 확인
type -a node

# 3. PATH 환경변수 확인
echo "$PATH"

# 4. 설치 경로 검색
find /usr/local /opt -type f -name node 2>/dev/null

# 5. 실제 파일이 있다면 권한 확인
ls -l /usr/local/bin/node

# 6. 절대경로로 실행 테스트
/usr/local/bin/node --version

# 7. PATH에 경로가 없다면 임시 추가
export PATH="$PATH:/usr/local/bin"

# 8. 다시 명령어 확인
command -v node
node --version

위 경로는 예시입니다. 실제 실행 파일의 위치는 배포판과 설치 방법에 따라 달라질 수 있습니다.

또한 command -v 결과가 비어 있어도 실행 파일이 다른 위치에 존재할 수 있으므로 바로 재설치하기보다 PATH와 설치 경로를 함께 확인하는 것이 좋습니다.

정리

리눅스 서버에서 Command Not Found 오류가 발생했다면 프로그램이 설치되지 않았다고 단정하기보다 명령어 검색 경로, 실행 파일 존재 여부, 사용자 환경 차이부터 확인해야 합니다.

가장 먼저 기억할 명령어는 다음 세 가지입니다.

command -v 명령어
type -a 명령어
echo "$PATH"

명령어가 설치되어 있다면 절대경로로 실행되는지 확인하고, PATH가 잘못됐다면 기존 경로를 유지하면서 필요한 디렉터리만 추가합니다.

특히 SSH에서는 정상 실행되는데 sudo, Cron, systemd에서만 실패한다면 각 실행 환경의 PATH와 설정을 비교해야 합니다. 명령어 재설치보다 현재 환경에서 실행 파일을 어떻게 찾고 있는지 확인하는 것이 문제를 빠르게 해결하는 핵심입니다.

10월 8, 2026

리눅스 서버에서 Device or Resource Busy 오류가 발생하는 원인과 해결 방법

리눅스 서버에서 디렉터리를 삭제하거나 디스크를 마운트 해제하려고 할 때 Device or Resource Busy 오류가 발생해 작업이 중단된 경험이 있으신가요? 특히 백업 작업이 끝난 뒤 외장 디스크를 분리하거나, Docker 컨테이너를 정리하고 디렉터리를 삭제하는 과정에서 이런 오류가 나타날 수 있습니다.

분명 사용 중인 프로그램이 없어 보이는데도 umount나 rm 명령이 실패하면 파일 권한이나 디스크 자체의 문제부터 의심하기 쉽습니다. 하지만 실제로는 다른 프로세스가 해당 경로를 열어두었거나, 현재 작업 디렉터리로 사용하거나, 하위 마운트가 남아 있는 경우가 많습니다.

이럴 때 무작정 kill -9으로 프로세스를 종료하거나 강제 마운트 해제를 시도하면 운영 중인 서비스와 데이터에 영향을 줄 수 있습니다. 따라서 먼저 어떤 자원이 사용 중인지 확인하고, 점유 원인에 맞는 방법으로 안전하게 해제해야 합니다.

이번 글에서는 Device or Resource Busy 오류가 발생하는 대표적인 상황을 구분하고, lsof, fuser, findmnt를 이용한 점검부터 프로세스 종료, 마운트 해제, Docker 환경 점검까지 실제 해결 순서대로 살펴봅니다.

Device or Resource Busy 핵심 명령어 한눈에 보기

오류가 발생한 경로가 /mnt/data라고 가정하면 다음 명령어부터 확인할 수 있습니다.

점검 목적	명령어
열린 파일 확인	`sudo lsof +D /mnt/data`
마운트 사용 프로세스	`sudo fuser -vm /mnt/data`
마운트 상태 확인	`findmnt -R /mnt/data`
현재 작업 위치 확인	`pwd`
프로세스 상세 정보	`ps -fp PID`

lsof +D는 지정한 디렉터리 아래를 재귀적으로 탐색하므로 파일이 많은 경로에서는 실행 시간이 길어질 수 있습니다. 마운트 해제가 목적이라면 fuser -vm과 findmnt를 먼저 확인하는 편이 효율적입니다.

Device or Resource Busy 오류 발생 후 fuser 명령어로 마운트 지점을 사용 중인 프로세스를 확인하는 예시입니다.

1. Device or Resource Busy 오류가 발생하는 이유

Device or Resource Busy는 리눅스에서 주로 EBUSY 오류에 해당합니다. 요청한 작업을 처리하려는 시점에 커널이 해당 자원을 사용 중이라고 판단해 작업을 거부하는 상황입니다.

다만 같은 오류 메시지라도 실행한 명령어에 따라 원인은 달라집니다.

umount 실패: 열린 파일, 작업 디렉터리, 하위 마운트 등이 남아 있는 경우
rm 또는 rmdir 실패: 삭제 대상이 마운트 지점이거나 커널이 사용 중인 특수 경로인 경우
mv 실패: 마운트 지점이나 사용 중인 특수 자원을 이동하려는 경우
Docker 작업 실패: 컨테이너의 볼륨이나 Bind Mount가 남아 있는 경우
네트워크 스토리지: NFS 등의 연결 상태나 마운트 참조가 정리되지 않은 경우

중요한 점은 일반 파일이 다른 프로세스에서 열려 있다는 이유만으로 항상 rm이 실패하는 것은 아니라는 것입니다. 리눅스에서는 열린 일반 파일도 삭제할 수 있으며, 파일을 사용 중인 프로세스가 종료될 때까지 실제 저장 공간이 유지될 수 있습니다.

따라서 어떤 명령에서 오류가 발생했는지 먼저 구분해야 불필요한 프로세스 종료나 권한 변경을 피할 수 있습니다.

2. lsof와 fuser로 자원을 사용하는 프로세스 찾기

마운트 지점이나 디렉터리를 사용 중인 프로세스를 찾으려면 lsof와 fuser를 사용할 수 있습니다.

먼저 디렉터리 아래에 열린 파일이 있는지 확인합니다.

sudo lsof +D /mnt/data

다음은 출력 예시입니다.

COMMAND  PID   USER  FD   TYPE  NAME
bash     2451  root  cwd  DIR   /mnt/data
python3  3180  app   5r   REG   /mnt/data/report.csv

여기서 확인해야 할 부분은 COMMAND, PID, FD, NAME입니다.

bash / 2451 / cwd: Bash 프로세스가 해당 디렉터리를 현재 작업 위치로 사용
python3 / 3180 / 5r: Python 프로세스가 파일을 읽기 모드로 열어둔 상태

마운트 지점을 기준으로 사용 중인 프로세스를 확인하려면 다음 명령어도 유용합니다.

sudo fuser -vm /mnt/data

출력 결과는 환경에 따라 다음과 비슷하게 나타납니다.

                     USER   PID ACCESS COMMAND
/mnt/data:           root  2451 ..c.. bash
                     app   3180 f.... python3

ACCESS에 표시되는 c는 현재 작업 디렉터리, f는 열린 파일과 관련된 사용 상태를 의미합니다.

다만 lsof와 fuser 결과가 비어 있다고 해서 마운트가 완전히 해제 가능한 상태라고 단정할 수는 없습니다. 하위 마운트, 다른 마운트 네임스페이스, 커널 수준의 참조 등도 확인해야 합니다.

3. 현재 작업 디렉터리와 하위 마운트 확인하기

터미널에서 마운트 지점 안으로 이동한 상태라면 해당 셸 자체가 마운트 해제를 방해할 수 있습니다.

예를 들어 다음과 같은 상황입니다.

cd /mnt/data
sudo umount /mnt/data

이때 다음 오류가 발생할 수 있습니다.

umount: /mnt/data: target is busy.

먼저 현재 작업 디렉터리를 확인합니다.

pwd

현재 위치가 마운트 지점 내부라면 다른 디렉터리로 이동합니다.

cd /
sudo umount /mnt/data

단, 다른 터미널이나 프로세스가 같은 마운트를 사용 중이라면 현재 셸만 이동해도 문제가 해결되지 않을 수 있습니다.

또한 마운트 지점 아래에 다른 파일시스템이 연결되어 있다면 상위 마운트를 해제하기 전에 하위 마운트를 먼저 확인해야 합니다.

findmnt -R /mnt/data

예를 들어 다음과 같이 표시될 수 있습니다.

TARGET            SOURCE      FSTYPE
/mnt/data         /dev/sdb1   ext4
/mnt/data/backup  /dev/sdc1   ext4

이 경우 /mnt/data/backup에 연결된 파일시스템부터 안전하게 해제한 뒤 상위 마운트를 점검해야 합니다.

4. 사용 중인 프로세스를 안전하게 종료하는 방법

fuser나 lsof로 PID를 확인했다면 먼저 해당 프로세스가 무엇인지 검증해야 합니다.

ps -fp 3180

서비스로 관리되는 프로세스라면 직접 PID를 종료하기보다 해당 서비스의 상태를 확인하는 것이 우선입니다.

sudo systemctl status 서비스명

정지해도 되는 서비스인지 확인했다면 정상적인 서비스 종료를 사용합니다.

sudo systemctl stop 서비스명

직접 실행한 프로세스라면 정상 종료 신호인 SIGTERM을 보낼 수 있습니다.

sudo kill -15 3180

프로세스가 종료됐는지 확인한 뒤 다시 마운트 해제를 시도합니다.

ps -p 3180
sudo fuser -vm /mnt/data
sudo umount /mnt/data

SIGTERM으로 종료되지 않는 경우에도 바로 강제 종료하기보다는 작업 상태와 서비스 영향을 확인해야 합니다.

kill -9는 정상 종료 처리를 거치지 못하게 하므로 데이터 쓰기 작업이 진행 중인 프로세스에는 특히 주의가 필요합니다. 또한 커널의 중단 불가능한 대기 상태인 D 상태의 프로세스는 SIGKILL을 보내도 즉시 종료되지 않을 수 있습니다.

5. Docker와 NFS 환경에서 오류가 발생하는 경우

Docker 컨테이너가 호스트 디렉터리를 Bind Mount로 사용하고 있다면 호스트에서 해당 경로를 정리하려 할 때 마운트 관련 충돌이 발생할 수 있습니다.

먼저 실행 중인 컨테이너를 확인합니다.

docker ps

특정 컨테이너의 마운트 설정을 확인하려면 다음과 같이 실행합니다.

docker inspect 컨테이너명 --format '{{json .Mounts}}'

해당 경로를 사용 중인 컨테이너가 확인됐다면 실제 운영 서비스에 영향을 주지 않는지 검토한 뒤 컨테이너를 정상적으로 중지하거나 마운트 설정을 수정해야 합니다.

docker stop 컨테이너명

NFS 같은 네트워크 파일시스템에서는 서버 연결 문제, 응답 지연, 마운트 참조 등으로 해제가 어려울 수 있습니다.

findmnt -T /mnt/data
sudo fuser -vm /mnt/data

이때 마운트 해제를 무리하게 반복하거나 파일을 사용 중인 프로세스를 일괄 종료하기보다는 네트워크 파일시스템의 연결 상태와 작업 중인 서비스를 함께 확인해야 합니다.

6. umount -l 또는 강제 해제를 사용해도 될까?

일반적인 마운트 해제가 실패할 때 umount -l 또는 umount -f를 해결 방법으로 소개하는 경우가 있습니다. 하지만 두 옵션은 의미와 적용 범위가 다릅니다.

umount -l은 Lazy Unmount로, 파일시스템을 현재 마운트 계층에서 분리하고 남아 있는 참조가 해제되면 정리를 완료하는 방식입니다.

sudo umount -l /mnt/data

이는 해당 파일시스템을 사용 중인 모든 프로세스가 종료됐다는 의미가 아닙니다. 따라서 일반적인 장애 해결 방법으로 무조건 사용하는 것은 권장하지 않습니다.

umount -f는 강제 해제 옵션이지만 모든 파일시스템에서 동일하게 동작하는 것은 아니며, 특히 응답하지 않는 네트워크 파일시스템 등에서 신중하게 검토해야 합니다.

sudo umount -f /mnt/data

운영 서버에서는 프로세스 점유 확인 → 서비스 정상 종료 → 하위 마운트 확인 → 일반 umount 재시도를 먼저 수행하고, Lazy 또는 강제 해제는 위험과 복구 절차를 이해한 경우에만 검토하는 것이 안전합니다.

실전 점검 순서

예를 들어 /mnt/data를 마운트 해제할 때 target is busy 오류가 발생했다면 다음 순서로 점검합니다.

# 1. 마운트 구조 확인
findmnt -R /mnt/data

# 2. 사용 중인 프로세스 확인
sudo fuser -vm /mnt/data

# 3. 열린 파일 확인
sudo lsof +D /mnt/data

# 4. PID 확인 후 상세 정보 조회
ps -fp 3180

# 5. 현재 작업 위치 변경
cd /

# 6. 원인을 해결한 뒤 다시 마운트 해제
sudo umount /mnt/data

# 7. 마운트 해제 여부 확인
findmnt -M /mnt/data

위 명령에서 PID 3180은 예시이므로 실제 서버에서 확인한 PID로 변경해야 합니다. 또한 프로세스를 종료하거나 마운트를 해제하기 전에는 서비스 영향과 데이터 쓰기 상태를 반드시 확인해야 합니다.

정리

리눅스 서버에서 Device or Resource Busy 오류가 발생했다면 단순한 파일 권한 문제로 판단하기보다 어떤 작업에서 오류가 발생했는지와 어떤 프로세스 또는 마운트가 해당 자원을 사용 중인지 확인하는 것이 우선입니다.

마운트 해제 오류라면 findmnt로 마운트 구조를 확인하고, fuser와 lsof로 사용 중인 프로세스를 추적합니다. 그다음 서비스의 정상 종료나 작업 디렉터리 변경 등으로 원인을 해결한 뒤 umount를 다시 실행하면 됩니다.

특히 kill -9, umount -l, umount -f 같은 명령은 상황에 따라 운영 중인 서비스에 영향을 줄 수 있으므로 원인을 확인하지 않은 상태에서 바로 실행하지 않는 것이 중요합니다.

10월 8, 2026

리눅스 서버에서 Stale File Handle 오류가 발생하는 이유와 해결 방법

리눅스 서버에서 NFS로 연결된 공유 디렉터리에 접근하려는데 갑자기 Stale file handle 오류가 나타나는 경우가 있습니다. 평소 정상적으로 사용하던 경로에서 ls, df, stat 명령어가 실패하거나, 파일을 읽고 쓰던 애플리케이션이 갑자기 파일 접근 오류를 기록하기도 합니다.

특히 NFS 서버를 재시작하거나 공유 디렉터리를 이동한 뒤, 스토리지 볼륨을 교체하거나 백업 데이터를 복원한 이후에 이런 문제가 발생할 수 있습니다. 파일이 실제로 존재하는데도 접근할 수 없어 권한 문제나 디스크 장애로 오해하기 쉽습니다.

하지만 Stale File Handle 오류는 클라이언트가 보유한 파일 식별 정보가 서버에서 더 이상 유효하지 않을 때 발생하는 경우가 많습니다. 즉, 경로 이름이 그대로 남아 있어도 해당 파일이나 디렉터리를 가리키던 기존 파일 핸들이 무효화된 상태일 수 있습니다.

이때 무조건 서버를 재부팅하거나 공유 디렉터리를 삭제하면 운영 중인 서비스에 추가 장애가 발생할 수 있습니다. 특히 여러 애플리케이션이 같은 NFS 마운트를 사용한다면 마운트 해제 전에 프로세스 점유 상태를 확인해야 합니다.

이번 글에서는 오류 발생 경로 확인 → NFS 마운트 상태 분석 → 파일 핸들 무효화 원인 점검 → 프로세스 점유 확인 → 안전한 마운트 복구 순서로 해결 방법을 살펴봅니다.

Stale File Handle 핵심 명령어 한눈에 보기

오류가 발생했다면 먼저 해당 디렉터리가 어떤 파일시스템에 연결되어 있는지, NFS 서버와 마운트 상태가 정상인지 확인해야 합니다. 아래 예시에서는 /mnt/shared를 NFS 마운트 경로로 사용합니다.

점검 목적	명령어
마운트 정보 확인	`findmnt -t nfs,nfs4`
NFS 마운트 목록	`mount -t nfs,nfs4`
NFS 서버 연결 확인	`ping -c 4 192.0.2.10`
파일 접근 오류 확인	`stat /mnt/shared`
점유 프로세스 확인	`sudo fuser -vm /mnt/shared`
NFS 클라이언트 통계	`nfsstat -m`
마운트 해제	`sudo umount /mnt/shared`
마운트 재연결	`sudo mount /mnt/shared`

중요한 점은 오류가 발생한 경로가 실제로 NFS 마운트인지 먼저 확인하는 것입니다. Stale File Handle은 NFS에서 대표적으로 발생하지만 파일 핸들을 사용하는 다른 파일시스템이나 스토리지 환경에서도 발생할 수 있습니다.

또한 ping이 성공했다고 해서 NFS 서비스가 정상적으로 동작한다는 의미는 아닙니다. 서버 연결과 파일시스템 접근 상태를 구분해서 확인해야 합니다.

리눅스 Stale File Handle 오류와 NFS 마운트 상태 확인 및 복구 방법 — NFS 공유 디렉터리에서 Stale File Handle 오류가 발생했을 때 마운트 상태와 프로세스 점유를 확인하는 예시입니다.

1. Stale File Handle 오류가 발생하는 원인

리눅스에서 Stale file handle은 일반적으로 ESTALE 오류와 관련이 있습니다.

NFS 클라이언트는 원격 서버의 파일이나 디렉터리에 접근할 때 서버가 제공하는 파일 핸들을 사용합니다. 파일 핸들은 단순한 파일 이름이 아니라 서버가 해당 파일시스템 객체를 식별하기 위한 정보를 포함합니다.

서버에서 파일이 삭제되거나 다른 객체로 교체되면 클라이언트가 이전에 저장한 파일 핸들이 더 이상 유효하지 않을 수 있습니다.

대표적인 원인은 다음과 같습니다.

NFS 서버의 파일 변경: 기존 파일이나 디렉터리가 삭제되고 새 객체로 교체된 경우
공유 디렉터리 재구성: NFS export 경로 또는 파일시스템 구성이 변경된 경우
스토리지 복원: 스냅샷 복구나 볼륨 교체로 파일 식별 정보가 달라진 경우
서버 재시작 후 변경: 재시작 과정에서 기존 파일 핸들이 더 이상 유효하지 않게 된 경우
마운트 구성 변경: 클라이언트가 이전 파일시스템 객체를 계속 참조하는 경우
애플리케이션의 오래된 참조: 프로세스가 삭제되거나 교체된 파일을 계속 사용하는 경우

다만 NFS 서버를 재시작했다는 이유만으로 항상 Stale File Handle 오류가 발생하는 것은 아닙니다. 일반적인 서버 재시작 이후에도 기존 파일 핸들이 유효하게 유지될 수 있습니다.

실제 원인은 서버의 파일시스템 객체나 export 구성이 어떻게 변경되었는지에 따라 달라집니다.

2. 실제 Stale File Handle 오류 메시지 확인하기

NFS 공유 디렉터리에서 문제가 발생하면 다음과 같은 메시지가 나타날 수 있습니다.

$ ls -la /mnt/shared

ls: cannot access '/mnt/shared':
Stale file handle

또는 특정 파일에 접근할 때 오류가 발생할 수 있습니다.

$ stat /mnt/shared/report.csv

stat: cannot statx '/mnt/shared/report.csv':
Stale file handle

이 메시지는 파일을 찾지 못했다는 No such file or directory 오류와 다릅니다.

파일 이름이나 경로가 존재하는 것처럼 보여도 클라이언트가 참조하는 파일 핸들이 서버에서 더 이상 유효하지 않아 파일 정보를 조회하지 못하는 상황일 수 있습니다.

특히 오류가 특정 파일에서만 발생하는지, 공유 디렉터리 전체에서 발생하는지 확인하면 문제 범위를 구분하는 데 도움이 됩니다.

3. findmnt와 mount로 NFS 마운트 상태 확인하기

가장 먼저 확인할 것은 오류가 발생한 경로가 어떤 원격 파일시스템에 연결되어 있는지입니다.

findmnt -t nfs,nfs4

다음은 출력 예시입니다.

TARGET       SOURCE                 FSTYPE OPTIONS
/mnt/shared  192.0.2.10:/exports/data nfs4   rw,relatime,vers=4.2

주요 항목은 다음과 같습니다.

TARGET: 클라이언트의 마운트 경로
SOURCE: NFS 서버 주소와 공유 경로
FSTYPE: NFS 파일시스템 유형
OPTIONS: 적용된 마운트 옵션

현재 마운트 목록을 확인하려면 다음 명령어도 사용할 수 있습니다.

mount -t nfs,nfs4

특정 경로의 마운트 정보를 확인할 때는 다음 명령어를 사용합니다.

findmnt --mountpoint /mnt/shared

단, 마운트 지점 자체가 아니라 하위 디렉터리에서 문제가 발생했다면 실제 경로에 적용되는 파일시스템을 별도로 확인해야 합니다.

또한 findmnt에 마운트가 표시된다고 해서 NFS 서버가 현재 정상적으로 응답한다는 의미는 아닙니다.

4. NFS 서버 연결과 커널 로그 점검하기

NFS 서버와 통신이 불안정하면 파일 접근 오류나 응답 지연이 함께 발생할 수 있습니다.

먼저 서버 연결 상태를 확인합니다.

ping -c 4 192.0.2.10

다만 ICMP가 차단된 환경에서는 ping이 실패해도 NFS 연결이 정상일 수 있습니다.

NFSv4에서 일반적으로 사용하는 TCP 2049번 포트의 접근 가능 여부를 확인하려면 다음과 같이 사용할 수 있습니다.

nc -vz -w 3 192.0.2.10 2049

이 명령어는 TCP 포트 접근 가능 여부를 확인하는 것으로, NFS 파일 핸들의 유효성까지 검증하지는 않습니다.

커널 로그에서도 관련 메시지를 검색합니다.

sudo journalctl -k -b | grep -Ei 'nfs|stale|server not responding'

예를 들어 다음과 같은 로그가 확인될 수 있습니다.

nfs: server 192.0.2.10 not responding, still trying

이 메시지는 서버 응답 지연이나 연결 문제를 나타낼 수 있지만 그 자체가 Stale File Handle의 직접적인 원인이라는 의미는 아닙니다.

ESTALE 오류와 네트워크 타임아웃은 서로 다른 문제일 수 있으므로 로그 발생 시각과 서버 변경 이력을 함께 확인해야 합니다.

5. NFS 마운트를 사용하는 프로세스 확인하기

마운트를 해제하기 전에 해당 경로를 사용 중인 프로세스가 있는지 확인해야 합니다.

sudo fuser -vm /mnt/shared

다음은 설명을 위한 출력 예시입니다.

                     USER        PID ACCESS COMMAND
/mnt/shared:         root       2451 ..c.. bash
                     app        3187 f.... python3

여기서 PID는 프로세스 번호, COMMAND는 실행 중인 프로그램입니다.

ACCESS 항목에서는 현재 작업 디렉터리나 열린 파일 등 마운트 사용 방식과 관련된 정보를 확인할 수 있습니다.

다만 Stale File Handle 상태에서는 일부 파일 접근 및 프로세스 조회 명령어가 실패하거나 응답이 지연될 수 있습니다.

운영 중인 데이터베이스, 웹 애플리케이션, 백업 프로세스가 해당 경로를 사용한다면 서비스 영향과 미완료 작업을 확인한 뒤 복구해야 합니다.

6. NFS 마운트 해제와 재연결로 복구하기

서버의 공유 경로와 파일시스템 구성이 정상이라는 사실을 확인했고, 마운트를 사용하는 서비스도 안전하게 중지할 수 있다면 마운트 해제와 재연결을 시도할 수 있습니다.

먼저 해당 디렉터리에서 작업 중인 셸이나 프로세스를 정리합니다.

그다음 정상적인 마운트 해제를 시도합니다.

sudo umount /mnt/shared

마운트 해제가 성공했다면 /etc/fstab에 해당 마운트가 등록되어 있는 경우 다음 명령어로 다시 연결할 수 있습니다.

sudo mount /mnt/shared

마운트가 복구됐는지 확인합니다.

findmnt --mountpoint /mnt/shared
ls -la /mnt/shared

마운트 재연결은 클라이언트가 오래된 파일 핸들을 다시 획득하는 데 도움이 될 수 있지만, 서버의 export 설정이나 파일시스템 자체에 문제가 있다면 재마운트만으로 해결되지 않을 수 있습니다.

또한 마운트 해제 이후에도 기존 파일 핸들을 보유한 애플리케이션은 정상적으로 복구되지 않을 수 있으므로 필요하다면 해당 애플리케이션을 안전하게 다시 시작해야 합니다.

7. Device or Resource Busy 오류로 마운트 해제가 실패하는 경우

NFS 마운트를 해제하려는데 다음과 같은 메시지가 나타날 수 있습니다.

umount: /mnt/shared: target is busy.

이는 해당 마운트를 사용 중인 프로세스나 하위 마운트 등이 존재할 때 발생할 수 있습니다.

먼저 사용 중인 프로세스를 확인합니다.

sudo fuser -vm /mnt/shared

하위 마운트가 있는지도 확인합니다.

findmnt -R /mnt/shared

문제의 원인이 된 서비스를 확인한 뒤 가능하면 서비스 관리자를 통해 정상 종료해야 합니다.

일반적인 프로세스라면 종료 가능 여부를 판단한 후 SIGTERM으로 정상 종료를 요청할 수 있습니다.

kill -15 3187

여기서 PID는 실제 확인된 프로세스 번호로 변경해야 합니다.

kill -9는 마지막 수단이며, NFS I/O를 기다리는 프로세스가 커널의 인터럽트 불가능한 대기 상태에 있다면 즉시 종료되지 않을 수 있습니다.

따라서 마운트가 사용 중이라는 이유만으로 모든 관련 프로세스를 강제 종료해서는 안 됩니다.

8. umount -l 또는 umount -f를 사용해도 될까?

마운트 해제가 실패할 때 다음 명령어를 해결 방법으로 소개하는 경우가 있습니다.

sudo umount -l /mnt/shared

-l은 lazy unmount 옵션입니다. 마운트 지점을 현재 파일시스템 네임스페이스에서 분리하고, 기존 참조가 해제되면 실제 정리가 완료되는 방식입니다.

따라서 명령어가 성공했다고 해서 기존 프로세스가 보유한 파일 핸들이 즉시 모두 해제되거나 NFS 연결이 완전히 정상화됐다고 볼 수는 없습니다.

다음 명령어는 강제 마운트 해제 옵션입니다.

sudo umount -f /mnt/shared

다만 -f의 동작은 파일시스템과 커널 구현에 따라 달라지며, NFS 연결이 응답하지 않는 상황에서도 항상 성공하는 것은 아닙니다.

운영 서버에서는 정상적인 마운트 해제와 서비스 종료를 먼저 시도하고, lazy 또는 force 옵션은 복구 절차와 영향 범위를 충분히 확인한 뒤 마지막 수단으로 검토하는 것이 좋습니다.

9. Stale File Handle 오류가 반복되는 경우 확인할 사항

재마운트 후에도 오류가 반복된다면 클라이언트 문제가 아니라 NFS 서버의 파일시스템 구성이나 애플리케이션 동작 방식에 원인이 있을 수 있습니다.

특히 다음 사항을 점검해야 합니다.

공유 경로 변경: NFS export 디렉터리가 이동되거나 교체됐는지 확인
파일시스템 교체: 서버의 공유 볼륨이 다른 파일시스템으로 변경됐는지 확인
스냅샷 복원: 복원 과정에서 기존 파일 핸들이 무효화됐는지 확인
애플리케이션 배포: 디렉터리를 삭제한 뒤 같은 이름으로 다시 생성하는 작업이 있는지 확인
클러스터 구성: 여러 NFS 서버가 일관된 파일 핸들을 제공하는지 확인
스토리지 로그: 서버 측 파일시스템 오류나 export 변경 기록 확인

특히 디렉터리를 삭제한 뒤 같은 이름으로 다시 생성하는 배포 방식은 기존 디렉터리를 참조하던 클라이언트에 영향을 줄 수 있습니다.

NFS 서버 관리 권한이 있다면 공유 설정과 실제 파일시스템 마운트 상태를 함께 점검해야 합니다.

다만 NFS 서버의 export 설정을 무작정 변경하거나 서비스를 반복해서 재시작하면 다른 클라이언트에도 영향을 줄 수 있으므로 주의해야 합니다.

실전 점검 순서

리눅스 서버에서 Stale File Handle 오류가 발생했다면 다음 순서로 점검할 수 있습니다.

# 1. NFS 마운트 목록 확인
findmnt -t nfs,nfs4

# 2. 오류 경로의 마운트 확인
findmnt --mountpoint /mnt/shared

# 3. 파일 접근 오류 확인
stat /mnt/shared

# 4. NFS 클라이언트 마운트 통계
nfsstat -m

# 5. 커널 로그 확인
sudo journalctl -k -b | grep -Ei 'nfs|stale|server not responding'

# 6. 마운트를 사용하는 프로세스 확인
sudo fuser -vm /mnt/shared

# 7. 하위 마운트 확인
findmnt -R /mnt/shared

# 8. 서비스 영향 확인 후 마운트 해제
sudo umount /mnt/shared

# 9. fstab에 등록된 마운트 재연결
sudo mount /mnt/shared

# 10. 복구 상태 확인
findmnt --mountpoint /mnt/shared
ls -la /mnt/shared

위 명령어는 정상적인 NFS 서버 연결과 공유 경로 구성이 확인된 환경을 기준으로 작성한 예시입니다.

실제 운영 환경에서는 마운트를 사용하는 애플리케이션을 먼저 확인하고, 데이터 손실이나 서비스 중단 가능성을 검토한 뒤 마운트 해제와 재연결을 진행해야 합니다.

정리

리눅스 서버에서 Stale File Handle 오류가 발생하는 이유는 대부분 클라이언트가 보유한 파일 핸들이 NFS 서버에서 더 이상 유효하지 않기 때문입니다.

특히 공유 디렉터리 변경, 파일시스템 교체, 스냅샷 복원, 오래된 파일 참조 등이 대표적인 원인입니다.

먼저 findmnt와 mount로 마운트 상태를 확인하고, fuser로 해당 경로를 사용하는 프로세스를 확인해야 합니다.

서버 구성이 정상이고 서비스 중단이 가능한 상황이라면 마운트 해제 후 재연결을 시도할 수 있습니다. 하지만 서버의 파일시스템 객체나 export 구성이 변경된 상태라면 근본 원인을 먼저 해결해야 합니다.

핵심 점검 순서는 오류 경로 확인 → NFS 상태 점검 → 서버 변경 이력 분석 → 프로세스 점유 확인 → 안전한 재마운트 → 재발 원인 제거입니다.

10월 8, 2026

서버에서 Address Already in Use 오류가 발생할 때 해결 방법

리눅스 서버에서 프로그램을 실행하거나 새로운 프로세스를 생성하려는데 갑자기 Cannot allocate memory 오류가 발생하는 경우가 있습니다. SSH 접속은 정상적으로 되지만 명령어 실행이 실패하거나, Python·Java·MySQL 같은 애플리케이션이 시작되지 않는 현상도 나타날 수 있습니다.

이런 오류가 발생하면 서버의 RAM이 모두 사용됐다고 생각하기 쉽습니다. 하지만 실제 물리 메모리가 부족한 경우뿐 아니라 Swap 부족, 프로세스의 가상 메모리 제한, 컨테이너 메모리 제한, 커널의 메모리 할당 정책 때문에도 문제가 발생할 수 있습니다.

특히 free -h에서 사용 가능한 메모리가 남아 있는데도 fork: Cannot allocate memory가 발생한다면 단순히 RAM 사용량만 확인해서는 원인을 찾기 어렵습니다.

이번 글에서는 메모리 상태 확인 → 프로세스별 사용량 분석 → OOM Killer 로그 점검 → Swap 및 시스템 제한 확인 → 원인별 해결 순서로 서버를 안전하게 점검하는 방법을 살펴봅니다.

Cannot Allocate Memory 핵심 명령어 한눈에 보기

오류가 발생했다면 먼저 아래 명령어로 시스템 메모리와 프로세스 상태를 확인합니다. 메모리가 심하게 부족한 서버에서는 새 명령어 실행 자체가 실패할 수 있으므로 가능하면 기존 SSH 세션이나 서버 콘솔을 유지한 상태에서 점검해야 합니다.

점검 목적	명령어
RAM·Swap 사용량	`free -h`
메모리 상태 변화	`vmstat 1 5`
메모리 사용 상위 프로세스	`ps aux --sort=-rss \| head -n 15`
OOM 관련 커널 로그	`sudo journalctl -k -b \| grep -Ei 'out of memory\|oom\|killed process'`
메모리 커밋 상태	`grep -E 'CommitLimit\|Committed_AS' /proc/meminfo`
프로세스 자원 제한	`ulimit -a`
Swap 장치 확인	`swapon --show`

가장 먼저 확인할 값은 단순한 free 메모리보다 실제로 새 작업에 사용할 수 있는 메모리를 추정하는 available 값입니다. 다만 available이 충분해 보여도 메모리 커밋 제한이나 cgroup 제한 등으로 할당에 실패할 수 있습니다.

리눅스 Cannot Allocate Memory 오류와 free vmstat OOM 메모리 점검 방법 — Cannot Allocate Memory 오류 발생 시 RAM, Swap, 메모리 사용 프로세스와 OOM 로그를 확인하는 예시입니다.

1. Cannot Allocate Memory 오류가 발생하는 이유

리눅스에서 Cannot allocate memory는 일반적으로 ENOMEM 오류와 관련이 있습니다. 프로그램이 메모리 할당이나 프로세스 생성에 필요한 자원을 확보하지 못했을 때 나타날 수 있습니다.

예를 들어 새로운 프로세스를 실행하려 할 때 다음과 같은 메시지가 표시될 수 있습니다.

bash: fork: Cannot allocate memory

또는 Python 프로그램에서 메모리 할당이 실패하면 다음과 같은 오류가 발생할 수 있습니다.

MemoryError

두 오류 모두 메모리 자원 문제와 관련될 수 있지만 발생 위치와 직접적인 원인은 다를 수 있습니다.

대표적인 원인은 다음과 같습니다.

물리 메모리 부족: 실행 중인 프로세스가 사용 가능한 RAM을 대부분 소비한 경우
Swap 부족: 메모리 압박 상황에서 추가적인 여유 공간이 부족한 경우
메모리 커밋 제한: 커널의 overcommit 정책에 따라 새로운 메모리 예약이 거부된 경우
프로세스 자원 제한: 주소 공간 크기 등 사용자 또는 프로세스별 제한에 도달한 경우
컨테이너 제한: Docker나 Kubernetes의 메모리 제한에 도달한 경우
커널 메모리 할당 문제: 특정 크기나 유형의 메모리 할당이 실패한 경우
애플리케이션 메모리 증가: 메모리 누수나 과도한 캐시 사용으로 사용량이 계속 늘어난 경우

따라서 메모리 부족 메시지가 나타났다고 해서 무조건 서버 RAM을 증설하거나 Swap부터 추가하는 것은 적절하지 않을 수 있습니다.

2. free -h로 RAM과 Swap 사용량 확인하기

가장 기본적인 점검은 free 명령어입니다.

free -h

다음은 설명을 위한 출력 예시입니다.

               total   used   free  shared  buff/cache  available
Mem:            7.7Gi  6.2Gi  210Mi   120Mi      1.3Gi      890Mi
Swap:           2.0Gi  1.7Gi  350Mi

여기서 중요한 항목은 다음과 같습니다.

total: 전체 메모리 크기
used: 사용 중인 메모리의 추정치
free: 현재 사용되지 않는 메모리
buff/cache: 버퍼와 파일 캐시 등으로 사용되는 메모리
available: 새로운 작업에 사용할 수 있는 메모리의 추정치

리눅스는 남는 메모리를 파일 캐시 등에 활용하므로 free 값이 작다는 사실만으로 메모리가 부족하다고 판단하면 안 됩니다.

또한 Swap 사용량이 높다는 이유만으로 현재 메모리 부족 상태라고 단정할 수도 없습니다. Swap에 오래전에 이동된 페이지가 남아 있을 수 있기 때문입니다.

실제 메모리 압박 여부는 available 값과 함께 Swap 입출력, 프로세스 사용량, OOM 로그를 비교해야 합니다.

3. vmstat로 메모리 부족과 Swap 활동 확인하기

메모리 부족이 일시적인지 지속적인지 확인하려면 vmstat 명령어를 사용할 수 있습니다.

vmstat 1 5

이 명령어는 1초 간격으로 시스템 상태를 5회 출력합니다.

메모리 관련 항목에서는 swpd, free, si, so 값을 확인합니다.

swpd: 사용 중인 가상 메모리의 Swap 양
si: Swap에서 메모리로 읽어 들이는 양
so: 메모리에서 Swap으로 내보내는 양
free: 사용하지 않는 메모리 양

si와 so 값이 반복적으로 높게 나타나고 서버 응답 속도도 느려진다면 메모리 압박으로 인해 Swap 입출력이 활발하게 발생하는 상황일 수 있습니다.

단, vmstat의 첫 번째 출력 행은 일반적으로 부팅 이후의 평균 통계를 포함하므로 실시간 상태를 분석할 때는 이후 출력 행도 함께 확인해야 합니다.

4. 메모리를 많이 사용하는 프로세스 찾기

메모리 사용량이 비정상적으로 높다면 어떤 프로세스가 메모리를 소비하고 있는지 확인해야 합니다.

ps aux --sort=-rss | head -n 15

위 명령어는 RSS 기준으로 메모리 사용량이 큰 프로세스를 확인하는 데 사용할 수 있습니다.

주요 항목은 다음과 같습니다.

PID: 프로세스 식별 번호
%MEM: 물리 메모리 대비 사용 비율
VSZ: 프로세스의 가상 주소 공간 크기
RSS: 실제 메모리에 상주하는 메모리 크기
COMMAND: 실행 중인 프로그램

특히 특정 프로세스의 RSS가 계속 증가한다면 애플리케이션의 메모리 누수나 캐시 정책을 점검할 필요가 있습니다.

다만 RSS에는 공유 메모리도 포함될 수 있으므로 여러 프로세스의 RSS를 단순 합산하면 실제 물리 메모리 사용량과 차이가 날 수 있습니다.

원인이 확인되지 않은 상태에서 메모리 사용량이 높다는 이유만으로 프로세스를 강제 종료하면 데이터 손실이나 서비스 장애가 발생할 수 있습니다.

5. OOM Killer 로그 확인하기

리눅스 커널은 메모리 부족 상황에서 시스템을 보호하기 위해 OOM Killer를 통해 프로세스를 종료할 수 있습니다.

최근 부팅 이후의 커널 로그에서 관련 메시지를 검색합니다.

sudo journalctl -k -b | grep -Ei 'out of memory|oom|killed process'

OOM이 발생한 경우 다음과 비슷한 메시지가 기록될 수 있습니다.

Out of memory: Killed process 2481 (java)
total-vm:4194304kB, anon-rss:2097152kB

위 예시는 커널이 메모리 부족 상황에서 Java 프로세스를 종료한 경우를 나타냅니다.

다만 Cannot Allocate Memory 오류가 발생했다고 해서 반드시 OOM Killer가 실행되는 것은 아닙니다. 메모리 할당이 거부되더라도 프로세스 종료 없이 오류만 반환될 수 있습니다.

또한 OOM 로그가 없다고 해서 메모리 부족 문제가 없었다고 단정할 수 없습니다. 로그 보존 상태와 커널 설정, 컨테이너 환경에 따라 확인 가능한 정보가 달라질 수 있습니다.

6. RAM이 남아 있는데 Cannot Allocate Memory가 발생하는 이유

free -h에서 available 메모리가 충분해 보여도 새로운 메모리 할당이 실패할 수 있습니다.

대표적으로 커널의 메모리 커밋 정책을 확인해야 하는 경우가 있습니다.

cat /proc/sys/vm/overcommit_memory

이 값은 커널이 메모리 할당 요청을 어떻게 판단할지 결정하는 설정입니다.

0: 커널의 휴리스틱에 따라 메모리 커밋을 판단
1: 메모리 커밋을 폭넓게 허용
2: 설정된 커밋 한도에 따라 엄격하게 제한

현재 커밋 상태는 다음 명령어로 확인합니다.

grep -E 'CommitLimit|Committed_AS' /proc/meminfo

Committed_AS가 CommitLimit에 가까운 상황에서 엄격한 overcommit 정책이 적용되고 있다면 새로운 메모리 예약이 거부될 수 있습니다.

다만 문제를 해결하기 위해 vm.overcommit_memory=1로 무조건 변경하는 것은 권장하지 않습니다. 실제 메모리 부족 위험이 사라지는 것이 아니라 메모리 할당 실패 시점과 시스템 동작이 달라질 수 있기 때문입니다.

7. ulimit과 프로세스별 메모리 제한 확인하기

특정 사용자나 프로그램에서만 오류가 발생한다면 프로세스별 자원 제한을 확인할 필요가 있습니다.

ulimit -a

특히 다음 항목을 확인합니다.

virtual memory: 프로세스의 가상 주소 공간 크기 제한
data seg size: 데이터 세그먼트 크기 제한
max user processes: 사용자에게 적용되는 프로세스 수 제한

프로세스 수 제한에 도달하면 일반적으로 Resource temporarily unavailable와 같은 다른 오류가 발생할 수 있으므로 메모리 할당 실패와 구분해야 합니다.

또한 systemd로 실행하는 서비스에는 셸의 ulimit과 별도로 자원 제한이 적용될 수 있습니다.

systemctl show myservice.service -p MemoryMax -p LimitAS -p LimitDATA

위 명령어의 myservice.service는 실제 서비스 이름으로 변경해야 합니다.

특정 서비스에서만 문제가 발생한다면 시스템 전체 메모리와 서비스별 제한을 함께 확인하는 것이 중요합니다.

8. Docker 컨테이너에서 메모리 부족이 발생하는 경우

Docker 컨테이너는 호스트 서버에 RAM이 충분히 남아 있어도 컨테이너에 설정된 메모리 제한에 도달할 수 있습니다.

실시간 컨테이너 메모리 사용량을 확인합니다.

docker stats --no-stream

특정 컨테이너의 메모리 제한과 OOM 종료 여부를 확인하려면 다음 명령어를 사용할 수 있습니다.

docker inspect mycontainer \
  --format 'Memory={{.HostConfig.Memory}} OOMKilled={{.State.OOMKilled}}'

Memory 값은 바이트 단위이며, 0이면 Docker의 해당 메모리 제한이 설정되지 않았다는 의미입니다.

OOMKilled가 true라면 컨테이너가 OOM 상황으로 종료됐음을 나타낼 수 있습니다. 다만 현재 상태와 종료 이력에 따라 추가 로그 확인이 필요할 수 있습니다.

컨테이너의 메모리 제한을 높이기 전에 애플리케이션이 정상적으로 메모리를 사용하는지, 메모리 누수가 있는지 먼저 확인해야 합니다.

9. Swap 추가가 필요한 상황과 주의할 점

서버에 Swap이 없거나 메모리 압박이 반복된다면 Swap 구성을 검토할 수 있습니다.

swapon --show
free -h

Swap은 메모리 부족 상황에서 일부 페이지를 디스크로 이동할 수 있도록 지원하지만 RAM을 대체하는 고속 메모리는 아닙니다.

특히 디스크가 느리거나 메모리 부족이 지속되는 서버에서는 Swap 사용량 증가로 응답 지연이 심해질 수 있습니다.

또한 Swap을 추가한다고 해서 프로세스의 주소 공간 제한, 컨테이너 메모리 제한, 특정 메모리 할당 실패가 모두 해결되는 것은 아닙니다.

따라서 실제 메모리 압박이 확인됐을 때 워크로드와 저장장치 성능을 고려해 Swap 크기를 결정해야 합니다.

실전 점검 순서

리눅스 서버에서 Cannot Allocate Memory 오류가 반복된다면 다음 순서로 원인을 좁힐 수 있습니다.

# 1. 전체 RAM과 Swap 확인
free -h

# 2. 메모리와 Swap 활동 확인
vmstat 1 5

# 3. 메모리 사용량이 큰 프로세스 확인
ps aux --sort=-rss | head -n 15

# 4. OOM Killer 로그 검색
sudo journalctl -k -b | grep -Ei 'out of memory|oom|killed process'

# 5. Swap 장치 확인
swapon --show

# 6. 메모리 커밋 정책 확인
cat /proc/sys/vm/overcommit_memory

# 7. 커밋 사용량 확인
grep -E 'CommitLimit|Committed_AS' /proc/meminfo

# 8. 현재 셸의 자원 제한 확인
ulimit -a

Docker나 systemd 서비스에서만 문제가 발생한다면 해당 컨테이너 또는 서비스에 적용된 메모리 제한도 추가로 확인합니다.

메모리 사용량이 높은 프로세스를 발견했다면 서비스의 정상적인 사용 패턴인지, 특정 요청 이후 급격히 증가하는지, 재시작 이후에도 반복되는지 비교해야 합니다.

운영 서버에서는 원인을 확인하기 전에 캐시를 강제로 비우거나 프로세스를 무작정 종료하는 방법을 우선 사용하지 않는 것이 좋습니다.

정리

리눅스 서버에서 Cannot Allocate Memory 오류가 발생하는 이유는 단순한 RAM 부족만이 아닙니다. Swap 부족, 메모리 커밋 정책, 프로세스별 자원 제한, Docker 메모리 제한 등 여러 요인이 영향을 줄 수 있습니다.

먼저 free -h로 전체 메모리를 확인하고, vmstat로 메모리 압박을 점검한 뒤, 프로세스 사용량과 OOM 로그를 함께 분석하는 것이 좋습니다.

특히 사용 가능한 RAM이 남아 있는데도 오류가 발생한다면 메모리 커밋 제한과 서비스·컨테이너별 메모리 제한을 확인해야 합니다.

핵심 점검 순서는 RAM·Swap 확인 → 메모리 사용 프로세스 분석 → OOM 로그 점검 → 시스템 제한 확인 → 원인에 맞는 설정 변경입니다.

10월 8, 2026

서버에서 Broken Pipe 오류가 반복적으로 발생하는 원인과 해결 방법

SSH로 서버에 접속해 작업하던 중 갑자기 client_loop: send disconnect: Broken pipe 오류가 나타나면서 연결이 끊어진 경험이 있으신가요? 또는 Nginx와 애플리케이션 서버를 운영하면서 로그에 Broken pipe나 Errno 32 메시지가 반복적으로 기록되는 경우도 있습니다.

특히 SSH 접속을 장시간 유지하거나, 대용량 파일을 전송하거나, 웹서버에서 응답 시간이 긴 요청을 처리할 때 이런 문제가 나타날 수 있습니다. 처음에는 서버가 다운됐거나 네트워크가 완전히 끊어졌다고 생각하기 쉽지만, 실제로는 상대방이 이미 연결을 종료했거나 TCP 연결이 더 이상 정상적으로 유지되지 않는 상태에서 데이터를 전송하려 할 때 발생하는 경우가 많습니다.

다만 Broken Pipe는 특정 프로그램 하나의 오류가 아닙니다. SSH 클라이언트, Python 애플리케이션, 웹서버, 프록시 서버 등 어느 계층에서 메시지가 발생했는지에 따라 점검해야 할 원인이 달라집니다.

이번 글에서는 Broken Pipe 오류 메시지 구분 → TCP 연결 상태 확인 → SSH KeepAlive 점검 → Nginx와 애플리케이션 로그 분석 → 안전한 설정 변경 순서로 반복적인 연결 종료 문제를 진단하는 방법을 살펴봅니다.

Broken Pipe 핵심 명령어 한눈에 보기

오류가 발생했다면 먼저 어떤 프로그램에서 메시지가 출력됐는지 확인해야 합니다. 아래 명령어는 Linux와 OpenSSH 환경에서 사용할 수 있는 대표적인 점검 방법입니다.

점검 목적	명령어
SSH 상세 로그	`ssh -vvv user@server.example.com`
SSH 클라이언트 설정	`ssh -G server.example.com`
TCP 연결 상태	`ss -tan`
SSH 서버 로그	`sudo journalctl -u sshd -n 100`
Nginx 오류 로그	`sudo tail -n 100 /var/log/nginx/error.log`
네트워크 경로 확인	`tracepath server.example.com`

Ubuntu와 Debian 계열에서는 SSH 서비스 이름이 ssh인 경우가 많으므로 journalctl -u ssh를 사용해야 할 수 있습니다. 또한 tracepath는 별도 패키지 설치가 필요할 수 있습니다.

서버 Broken Pipe 오류 메시지와 SSH 연결 상태 점검 화면 — SSH 연결 중 Broken Pipe 오류가 발생했을 때 연결 로그와 TCP 상태를 확인하는 터미널 화면 예시입니다.

1. Broken Pipe 오류는 어떤 상황에서 발생할까?

리눅스에서 Broken pipe는 일반적으로 EPIPE 오류와 관련이 있습니다. 파이프 또는 소켓의 상대편이 더 이상 데이터를 받지 않는 상태에서 쓰기 작업을 시도할 때 발생할 수 있습니다.

예를 들어 서버에서 다음과 같은 오류가 표시될 수 있습니다.

client_loop: send disconnect: Broken pipe

또는 Python 애플리케이션에서는 다음과 같이 나타날 수 있습니다.

BrokenPipeError: [Errno 32] Broken pipe

이 두 메시지는 모두 Broken Pipe와 관련이 있지만 동일한 원인으로 발생했다고 단정할 수는 없습니다.

SSH: 연결이 끊어진 상태에서 클라이언트가 데이터를 보내려는 경우
웹 애플리케이션: 클라이언트가 응답을 기다리지 않고 연결을 종료한 경우
프록시 환경: 중간 프록시 또는 로드밸런서가 연결을 종료한 경우
파일 전송: 전송 도중 네트워크 연결이 끊기거나 상대 프로세스가 종료된 경우
셸 파이프라인: 데이터를 받는 명령어가 먼저 종료된 경우

따라서 오류가 발생한 위치를 구분하지 않고 SSH 설정이나 Nginx 타임아웃만 변경하는 것은 올바른 접근이 아닙니다.

2. SSH 접속 중 Broken Pipe가 반복되는 경우

SSH 연결을 장시간 유지하다가 갑자기 끊기는 경우라면 클라이언트와 서버 사이의 네트워크 연결 상태부터 확인해야 합니다.

특히 방화벽, NAT 장비, VPN 또는 로드밸런서가 오랫동안 데이터 전송이 없는 연결을 정리하면서 문제가 발생할 수 있습니다.

먼저 상세 로그를 활성화해 SSH에 접속합니다.

ssh -vvv user@server.example.com

연결이 끊어지는 시점의 로그를 확인하면 키 교환, 인증, 세션 유지 또는 데이터 전송 중 어느 단계에서 문제가 발생했는지 판단하는 데 도움이 됩니다.

현재 적용되는 SSH 클라이언트 설정은 다음과 같이 확인할 수 있습니다.

ssh -G server.example.com | grep -Ei 'serveralive|tcpkeepalive'

여기서 ServerAliveInterval은 SSH 클라이언트가 일정 시간 동안 서버로부터 데이터를 받지 못했을 때 서버에 응답을 요청하는 간격을 지정합니다.

ServerAliveCountMax는 응답이 없는 상태에서 허용할 연속적인 서버 응답 요청 횟수와 관련된 설정입니다.

이 값들은 네트워크 장비의 유휴 연결 정리 문제를 완화하는 데 도움이 될 수 있지만, 실제 네트워크 장애를 복구하거나 모든 연결 끊김을 방지하는 설정은 아닙니다.

3. SSH KeepAlive 설정으로 유휴 연결 끊김 완화하기

SSH 접속이 일정 시간 사용하지 않았을 때만 반복적으로 끊긴다면 클라이언트의 KeepAlive 설정을 검토할 수 있습니다.

먼저 현재 접속에만 옵션을 적용해 테스트합니다.

ssh -o ServerAliveInterval=60 \
    -o ServerAliveCountMax=3 \
    user@server.example.com

위 설정은 서버로부터 데이터를 받지 못한 시간이 60초에 도달하면 서버 응답을 요청하도록 구성합니다. 연속적으로 응답이 없으면 설정에 따라 연결을 종료할 수 있습니다.

테스트 결과 유휴 상태에서의 연결 끊김이 줄어든다면 클라이언트 설정 파일에 해당 서버에 대한 설정을 추가할 수 있습니다.

Host myserver
    HostName server.example.com
    User user
    ServerAliveInterval 60
    ServerAliveCountMax 3

위 내용은 SSH 클라이언트의 ~/.ssh/config에 추가하는 예시입니다.

모든 서버에 일괄 적용하기보다 실제로 문제가 발생하는 서버에만 설정한 뒤 연결 안정성을 확인하는 것이 좋습니다.

4. SSH 서버 측 ClientAlive 설정 확인하기

클라이언트 설정으로 문제가 해결되지 않는다면 SSH 서버의 연결 유지 및 세션 종료 설정을 확인할 수 있습니다.

서버에서 현재 적용되는 SSHD 설정을 확인합니다.

sudo sshd -T | grep -Ei 'clientalive|tcpkeepalive'

SSH 서버에서는 ClientAliveInterval과 ClientAliveCountMax 설정을 사용할 수 있습니다.

예를 들어 다음과 같은 설정을 검토할 수 있습니다.

ClientAliveInterval 60
ClientAliveCountMax 3

다만 이 설정은 SSH 서버가 클라이언트의 응답 상태를 확인하는 데 사용되며, 유휴 연결을 무조건 유지하는 기능과 동일하지 않습니다.

설정을 변경해야 한다면 기존 SSH 세션을 유지한 상태에서 설정 파일의 문법을 먼저 검사해야 합니다.

sudo sshd -t

설정이 정상임을 확인한 뒤 실제 서비스 이름과 운영 환경에 맞게 SSH 서비스를 다시 불러오거나 재시작할 수 있습니다.

원격 서버에서 SSH 설정을 잘못 변경하면 재접속이 불가능해질 수 있으므로 콘솔 접근 수단을 확보한 상태에서 작업하는 것이 안전합니다.

5. Nginx와 애플리케이션에서 Broken Pipe가 발생하는 경우

웹서버 로그에 Broken Pipe가 반복적으로 기록된다면 SSH 설정이 아니라 HTTP 연결과 애플리케이션 응답 처리 과정을 확인해야 합니다.

예를 들어 클라이언트가 요청을 보낸 뒤 응답을 기다리다가 브라우저를 닫거나 연결을 종료했는데, 서버가 뒤늦게 응답 데이터를 전송하려 하면 쓰기 오류가 발생할 수 있습니다.

먼저 Nginx 오류 로그를 확인합니다.

sudo tail -n 100 /var/log/nginx/error.log

Access Log에서는 요청 경로와 상태 코드, 응답시간을 함께 확인하는 것이 좋습니다. 단, 응답시간 필드가 기록되는지는 실제 로그 포맷에 따라 다릅니다.

sudo tail -n 100 /var/log/nginx/access.log

Nginx의 499 상태 코드는 Nginx가 응답을 완료하기 전에 클라이언트가 연결을 종료했음을 나타내는 Nginx 전용 로그 코드입니다.

하지만 Broken Pipe 오류가 발생했다고 해서 반드시 499가 함께 기록되는 것은 아닙니다. 애플리케이션이 프록시나 클라이언트로 데이터를 보내는 과정에서 발생한 별도의 소켓 오류일 수도 있습니다.

따라서 오류가 발생한 시간대의 Nginx 로그와 애플리케이션 로그를 함께 비교해야 원인을 좁힐 수 있습니다.

6. Python 애플리케이션의 BrokenPipeError 확인하기

Python 서버나 스크립트에서는 다음과 같은 오류가 발생할 수 있습니다.

BrokenPipeError: [Errno 32] Broken pipe

예를 들어 HTTP 클라이언트가 연결을 종료한 뒤 애플리케이션이 응답을 전송하려는 상황에서 발생할 수 있습니다.

또한 셸에서 다음과 같은 파이프라인을 실행할 때도 출력을 받는 명령어가 먼저 종료되면서 Broken Pipe가 발생할 수 있습니다.

python3 generate_data.py | head -n 10

head가 필요한 10줄을 읽고 종료하면 데이터를 계속 출력하려는 Python 프로세스에서 BrokenPipeError가 발생할 수 있습니다.

이런 경우는 반드시 네트워크 장애를 의미하지 않습니다. 파이프를 읽는 프로세스가 먼저 종료된 정상적인 실행 흐름에서 발생한 부수적인 오류일 수도 있습니다.

반면 웹 애플리케이션에서 동일한 오류가 반복된다면 클라이언트 연결 종료 시점, 응답 생성 시간, 프록시 타임아웃 및 요청 처리 구조를 함께 분석해야 합니다.

7. TCP 연결과 네트워크 상태 확인하기

Broken Pipe가 SSH와 웹 애플리케이션에서 동시에 발생한다면 서버의 네트워크 상태와 TCP 연결 상태도 확인할 필요가 있습니다.

먼저 TCP 연결 목록을 확인합니다.

ss -tan

특정 SSH 연결을 확인하려면 다음과 같이 포트를 필터링할 수 있습니다.

ss -tan '( sport = :22 or dport = :22 )'

주요 TCP 상태에는 ESTAB, TIME-WAIT, CLOSE-WAIT 등이 있습니다.

특히 CLOSE-WAIT 상태가 지속적으로 누적된다면 상대방이 연결 종료를 요청했지만 로컬 애플리케이션이 소켓을 적절하게 정리하지 못하고 있을 가능성을 확인해야 합니다.

다만 특정 TCP 상태가 보인다는 이유만으로 Broken Pipe의 원인이 확정되는 것은 아닙니다. 오류 발생 시점의 로그와 연결 상태를 함께 비교해야 합니다.

네트워크 경로 점검에는 다음 명령어를 사용할 수 있습니다.

ping -c 5 server.example.com
tracepath server.example.com

ICMP 응답이 차단된 환경에서는 ping이나 tracepath가 실패해도 SSH나 HTTP 연결은 정상일 수 있습니다. 따라서 이 결과만으로 네트워크 장애 여부를 판단해서는 안 됩니다.

8. 타임아웃 설정을 무조건 늘리면 해결될까?

Broken Pipe가 반복되면 SSH KeepAlive나 Nginx의 proxy_read_timeout 값을 크게 늘리는 방법을 먼저 떠올리기 쉽습니다.

하지만 타임아웃 설정은 실제로 어떤 연결이 먼저 종료되는지 확인한 뒤 조정해야 합니다.

예를 들어 Nginx가 업스트림 응답을 기다리다가 타임아웃이 발생한 상황과 브라우저가 먼저 연결을 종료한 상황은 해결 방향이 다릅니다.

응답시간이 긴 API라면 다음 항목을 함께 확인해야 합니다.

애플리케이션 요청 처리 시간
데이터베이스 쿼리 지연
리버스 프록시와 업스트림 타임아웃
로드밸런서 및 CDN 연결 제한
클라이언트의 요청 취소 및 타임아웃
대용량 응답 전송과 스트리밍 처리 방식

타임아웃을 크게 늘리는 것만으로 근본 원인이 해결되는 것은 아니며, 불필요하게 오래 유지되는 연결이 늘어날 수도 있습니다.

실전 점검 순서

Broken Pipe 오류가 반복된다면 먼저 발생 위치를 구분하고 다음 순서로 점검하는 것이 좋습니다.

# 1. SSH 상세 로그 확인
ssh -vvv user@server.example.com

# 2. SSH 클라이언트 KeepAlive 설정 확인
ssh -G server.example.com | grep -Ei 'serveralive|tcpkeepalive'

# 3. 서버 측 SSH 설정 확인
sudo sshd -T | grep -Ei 'clientalive|tcpkeepalive'

# 4. TCP 연결 상태 확인
ss -tan

# 5. Nginx 오류 로그 확인
sudo tail -n 100 /var/log/nginx/error.log

# 6. Nginx Access Log 확인
sudo tail -n 100 /var/log/nginx/access.log

# 7. SSH 서버 로그 확인
sudo journalctl -u sshd -n 100

위 명령어는 모든 서버에서 한꺼번에 실행해야 하는 절차가 아닙니다. SSH에서만 오류가 발생한다면 SSH와 네트워크를 우선 점검하고, 웹 애플리케이션에서만 발생한다면 해당 애플리케이션과 프록시 로그부터 확인해야 합니다.

설정 변경 전에는 오류 발생 시간과 빈도, 특정 요청 또는 특정 사용자에게만 발생하는지, 유휴 상태에서 발생하는지 등을 기록해두면 변경 후 개선 여부를 비교하기 쉽습니다.

정리

서버에서 Broken Pipe 오류가 반복적으로 발생한다면 상대방이 데이터를 더 이상 받지 않는 상태에서 쓰기 작업이 발생했는지부터 확인해야 합니다.

SSH에서는 유휴 연결 종료, 네트워크 경로, KeepAlive 설정을 확인하고, Nginx나 애플리케이션에서는 클라이언트 연결 종료와 응답시간, 프록시 타임아웃을 함께 분석해야 합니다.

특히 Broken Pipe가 발생했다는 사실만으로 서버 다운이나 네트워크 장애를 단정할 수는 없습니다. 프로그램별 오류 메시지와 발생 시점의 로그를 비교해 어느 쪽에서 연결이 종료됐는지 확인하는 것이 중요합니다.

핵심 점검 순서는 오류 발생 위치 확인 → 연결 종료 시점 분석 → TCP·로그 점검 → 필요한 설정만 변경 → 재발 여부 확인입니다.

10월 8, 2026