ERR_SERVER_ALREADY_LISTEN

의미

ERR_SERVER_ALREADY_LISTEN은 이미 수신 중인 net.Server에 server.listen() 메서드를 호출했음을 나타냅니다. HTTP, HTTPS, HTTP/2 Server를 포함한 모든 net.Server 인스턴스에 적용됩니다.

확인

1. 현재 화면 또는 로그의 error.code 값이 ERR_SERVER_ALREADY_LISTEN과 일치하는지 확인합니다.
2. 일치하면 해당 오류는 이미 수신 중인 서버에 server.listen()을 호출한 경우로 식별합니다.

Node.js는 오류 메시지 문자열이 버전 사이에 변경될 수 있으므로 오류 식별에 error.code 사용을 권장합니다.

출처

• Node.js Errors 문서 (새 창에서 열림)

진단 기록

먼저 문제가 발생한 URL 또는 화면, 표시 시각, 사용한 플랫폼과 배포 버전을 기록합니다. 화면과 로그에서 오류 문자열이 일부만 보이면 앞뒤 문장을 포함해 원문을 보존하고, 민감한 값은 가립니다.

다음 순서로 관찰값을 대조합니다.

1. 현재 오류 객체 또는 로그의 오류 코드가 ERR_SERVER_ALREADY_LISTEN인지 확인합니다.
2. 오류 코드가 일치하면 이미 수신 중인 net.Server에 server.listen()이 호출된 경우로 판정합니다.

각 항목은 확인한 값과 확인하지 못한 이유를 함께 기록해야 합니다. 이 문서의 조건과 실제 관찰값이 다르면 원인을 단정하지 말고, 문제 해결 시작 가이드에서 더 넓은 분기를 선택하십시오.

판정 기준

오류 문자열이 일치한다는 사실만으로 원인이 확정되지는 않습니다. 같은 문구가 여러 환경에서 나타날 수 있으므로 웹서버·런타임·운영체제·최근 변경 사항을 함께 비교합니다. 한 단계에서 기대한 값이 나오지 않으면 다음 단계로 넘어가지 말고 해당 환경의 공식 문서를 우선 확인합니다.

안전한 다음 단계

검사 전에 백업과 변경 이력을 확인하고, 비밀번호·세션 쿠키·인증 토큰·개인정보를 공개 로그나 문의 내용에 넣지 않습니다. 설정·권한·데이터를 변경해야 한다면 영향 범위와 되돌리는 방법을 먼저 기록한 뒤 운영 시간과 승인 절차에 맞춰 진행합니다.

원인 분포

[Observation] 관측된 사례 기준으로 세 건 모두 서버 수신 시작이 중복되거나, 테스트 실행 흐름에서 서버 시작이 한 번만 수행되도록 보장되지 않은 상황과 관련되었습니다.

• [Observation] 동일 서버의 listen()을 두 번 호출한 사례가 두 건이었습니다.
• [Observation] 비동기 테스트 훅에서 서버 시작을 한 번만 수행하고 완료를 기다리지 않은 실행 흐름이 한 건이었습니다.
• [Hypothesis] 이 문서의 사례 집합에서는 포트 자체보다 listen() 호출 경로와 서버 시작 생명주기 관리가 주요 확인 대상일 가능성이 있습니다.

오진 함정

• [Observation] Node.js 버전이나 Ubuntu 환경에서만 발생하는 문제로 보일 수 있지만, 사례 1과 사례 3에서도 각각 Heroku와 Fastify 테스트 환경에서 발생했습니다.
• [Observation] HTTPS 서버에서는 createServer(...).listen(port)와 별도의 server.listen(port)가 함께 실행되는지 확인해야 합니다.
• [Observation] 테스트에서는 요청 코드보다 먼저 서버 시작이 완료되었는지, 테스트 훅이 서버 시작을 반복 실행하지 않는지 확인해야 합니다.

환경 매트릭스

환경	증상과 관련된 실행 흐름	수정
Heroku, Node.js, Socket.IO	다른 모듈에서 동일 서버의 listen()이 두 번째로 호출됨	중복 호출 제거
Ubuntu, Node.js HTTPS	createServer(...).listen(port) 뒤에 server.listen(port)을 다시 호출함	두 호출 중 하나만 유지
Fastify, chai-http 테스트	비동기 서버 시작이 끝나기 전에 요청을 실행함	시작 완료를 기다리고 테스트 훅에서 한 번만 시작

진단 순서

1. [Observation] 오류가 발생한 서버 인스턴스의 listen() 호출 지점을 모두 확인합니다.
2. [Observation] createServer(...).listen(port)와 별도의 server.listen(port)이 함께 실행되는지 확인합니다.
3. [Observation] 다른 모듈이나 테스트 훅이 동일 서버의 시작 함수를 다시 호출하는지 확인합니다.
4. [Observation] 비동기 서버 시작이 완료된 뒤 요청이 실행되는지 확인합니다.
5. [Observation] 중복 호출을 제거하거나, 테스트 훅에서 서버를 한 번만 시작하고 시작 완료를 기다리도록 수정합니다.