EADDRINUSE: address already in use — 포트 비우기

안녕하세요, BlueByte입니다. EADDRINUSE는 앱이 쓰려는 포트를 이미 무언가 쥐고 있다는 뜻일 뿐입니다 — 대개 종료되지 않은 앱 자신의 이전 실행이죠. 오늘은 무엇이 쥐고 있는지 정확히 찾고, 멈출지 앱을 옮길지 정하고, 포트가 비어 보이는데도 안 바인드되는 경우까지 짚는 순서로 가보겠습니다.

이 오류가 뜻하는 것

서버 시작이 실패합니다:

Error: listen EADDRINUSE: address already in use :::3000

포트가 점유됐습니다. 다른 프로세스 — 대개 종료되지 않은 같은 앱의 이전 실행 — 가 이미 쥐고 있어 새 프로세스가 바인드하지 못합니다. 해결은 쥔 쪽이 죽일 수 있는 남은 인스턴스인지 실제로 필요한 서비스인지에 달렸으니, 첫 일은 그것을 식별하는 것입니다.

포트가 이미 점유된 이유

인터페이스당 특정 TCP 포트는 한 프로세스만 리스닝합니다. EADDRINUSE가 나는 때:

• 이전 인스턴스가 아직 실행 중 — 가장 흔한 경우, 특히 크래시나 서버를 멈추지 않고 닫은 터미널 후.
• 다른 서비스가 정당하게 같은 포트를 씀.
• 크래시한 프로세스가 소켓을 연 채 — 풀릴 때까지 포트가 쥐여 있음.
• 빠른 재시작에서 이전 소켓이 TIME_WAIT이라 포트가 아직 재바인드 불가.

무엇이 쥐고 있는지 정확히 찾기

눈감고 죽이지 말고 쥔 것을 먼저 찾으세요. Linux:

ss -ltnp | grep :3000

macOS:

lsof -nP -iTCP:3000 -sTCP:LISTEN

둘 다 PID와 프로그램명을 출력합니다. 이름이 이전 실행의 내 앱이면 남은 인스턴스, 의존하는 다른 것이면 죽이지 말고 앱을 옮기세요. LISTEN으로 아무것도 안 뜨는데 빠른 재시작에서 바인드 못 하면 포트가 TIME_WAIT — ss -tan | grep :3000이 보여줍니다.

쥔 것을 멈추거나, 앱을 옮기기

1. 남은 인스턴스면 멈춥니다:

kill 12345          # 정상
kill -9 12345       # 무시하면

2. 쥔 게 필요한 서비스면 앱을 다른 포트로:

PORT=3001 npm start

실제 사례: 분리된 개발 서버

Ctrl+C로 개발 서버를 멈추고 파일을 고친 뒤 재시작하는데 EADDRINUSE :::3000으로 실패합니다. ss -ltnp | grep :3000이 이전 실행의 node 프로세스가 아직 리스닝 중임을 보여줍니다 — 앞서 터미널을 닫은 게 멈춘 게 아니라 분리한 것입니다. 그 PID를 kill하고 ss에 더는 안 뜨는 것을 확인한 뒤 서버를 시작하니 깨끗이 바인드합니다. 빠른 재시작에서 계속 이러니, 개발 서버가 주소를 재사용하게 바꿔 남은 TIME_WAIT 소켓이 재바인드를 막지 않게 합니다.

포트가 내 것인지 확인

서버를 다시 시작해 바인드를 확인:

ss -ltnp | grep :3000   # 이제 새 프로세스만 표시

깨끗이 시작하고 리스너가 내 앱이면 포트는 내 것입니다.

다시 겪지 않으려면

서버를 깨끗이 종료하고(창을 닫지 말고 Ctrl+C), systemd·pm2·Docker 같은 감독자가 옛 프로세스를 계속 되살리면 PID를 손으로 죽이지 말고 거기서 멈추세요. 빠른 개발 재시작엔 주소 재사용을 켜 소켓이 남지 않게 하세요.

ECONNREFUSED·EACCES와의 구분

EADDRINUSE는 로컬 충돌 — 내 기기의 포트가 점유됨. ECONNREFUSED는 반대편 — 연결하려는데 리스너가 없음. 1024 미만 낮은 포트의 EACCES는 충돌이 아니라 권한 문제 — 그 포트엔 상승 권한이 필요합니다. EADDRINUSE를 만나면 무언가 죽이기 전에 ss/lsof로 쥔 것을 식별하세요.