Error: listen EADDRINUSE 에러 해결법 – 원인 분석부터 완벽 해결까지

🚨 도입부

Node.js 개발을 하다 보면 ‘Error: listen EADDRINUSE’라는 에러 메시지를 접하게 될 때가 있습니다. 특히, 서버를 시작하려는 순간 이 메시지가 뜬다면, 많은 개발자들이 당황하고 좌절할 수밖에 없습니다. 이 에러는 주로 포트가 이미 사용 중일 때 발생하는데, 이는 여러 가지 시나리오에서 나타날 수 있습니다. 예를 들어, 개발 환경에서 서버를 재시작하려고 할 때, 또는 같은 포트를 여러 인스턴스에서 동시에 사용하려고 할 때 발생할 수 있습니다.

이 글을 통해, 여러분은 이 에러의 구체적인 원인과 각각의 해결책을 단계별로 배우게 될 것입니다. 예상 해결 시간은 여러분의 경험에 따라 다르겠지만, 이 글을 차근차근 따라온다면 빠르게는 몇 분에서 길게는 30분 이내에 문제를 해결할 수 있을 것입니다. 난이도는 초급에서 중급 수준으로, Node.js에 대한 기본적인 이해만 있다면 문제없이 따라올 수 있습니다.

🔍 에러 메시지 상세 분석

‘Error: listen EADDRINUSE’는 Node.js에서 서버를 시작할 때 특정 포트가 이미 사용 중이라는 것을 의미합니다. 변형된 메시지 예로는 ‘Error: listen EADDRINUSE 127.0.0.1:3000’과 같이 특정 IP 주소와 포트 번호가 포함될 수 있습니다. 이 에러는 다음과 같은 다양한 상황에서 발생할 수 있습니다:

• 서버를 종료하지 않고 재시작하려 할 때
• 다른 애플리케이션이 동일한 포트를 사용 중일 때
• 운영체제의 포트 해제 시간이 지나지 않았을 때
• 동일한 포트를 여러 인스턴스에서 동시에 사용하려고 할 때
• 잘못된 네트워크 설정으로 인해 발생할 때

에러 메시지는 ‘Error’, ‘listen’, ‘EADDRINUSE’로 구성되어 있습니다. 각각의 의미는 다음과 같습니다: ‘Error’는 일반적인 오류를, ‘listen’은 서버가 포트를 열고 대기 중임을, ‘EADDRINUSE’는 주소가 사용 중임을 나타냅니다. 초보자라면, 에러 메시지의 각 부분을 이렇게 나누어 읽어보는 것이 도움이 됩니다.

이 에러와 혼동하기 쉬운 다른 에러로는 ‘Error: listen EACCES’가 있습니다. 이는 권한 문제가 있는 경우 발생합니다. 이 두 에러를 구분하는 것이 중요합니다.

🧐 발생 원인 분석

이 에러의 주요 원인은 다음과 같으며, 각 원인은 특정 상황에서 발생할 수 있습니다:

1. 포트 중복 사용: 동일한 포트를 두 개 이상의 프로세스가 사용하려고 시도할 때 발생합니다. 예를 들어, 로컬 개발 환경에서 서버를 재시작하는 경우 이전 프로세스가 포트를 점유하고 있는 경우가 많습니다.
2. 서버 종료 실패: 이전에 시작한 서버가 제대로 종료되지 않아 포트가 계속 점유될 수 있습니다. 이는 서버 코드에 문제가 있거나 종료 절차가 올바르게 수행되지 않았을 때 발생할 수 있습니다.
3. 운영체제 포트 해제 지연: 일부 운영체제는 포트를 사용할 수 있도록 해제하는 데 시간이 걸릴 수 있습니다. 특히, Windows나 macOS에서 이 문제가 자주 발생합니다.
4. 다른 애플리케이션의 포트 사용: 종종 웹 서버나 데이터베이스 같은 다른 애플리케이션이 해당 포트를 사용 중일 수 있습니다. 이는 일반적으로 개발 환경에서 발생합니다.
5. 잘못된 네트워크 설정: 네트워크 설정 오류로 인해 포트가 예상치 못한 방식으로 사용될 수 있습니다. 이는 주로 복잡한 네트워크 환경에서 발생합니다.

각 원인의 확인 방법은 다양합니다. 예를 들어, 터미널에서 ‘lsof -i :<포트번호>‘ 명령을 사용하면 현재 포트를 사용 중인 프로세스를 확인할 수 있습니다. Windows에서는 ‘netstat -ano | findstr :<포트번호>‘ 명령을 통해 비슷한 정보를 얻을 수 있습니다.

✅ 해결 방법

즉시 해결

1. 프로세스 종료: 사용 중인 포트를 점유한 프로세스를 종료합니다. Mac과 Linux에서는 ‘lsof -i :<포트번호>‘를 통해 확인한 후 ‘kill -9 ‘ 명령으로 프로세스를 종료할 수 있습니다. Windows에서는 ‘taskkill /PID /F’ 명령을 사용합니다.
2. 서버 코드 변경: 포트를 변경하고 다시 시도합니다. 이를테면, 3000번 포트에서 3001번 포트로 변경합니다. 이를 위해 코드를 수정합니다:

const http = require('http');

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World');
});

const port = 3001; // 포트를 3001로 변경
server.listen(port, '127.0.0.1', () => {
  console.log(`Server running at http://127.0.0.1:${port}/`);
});

3. 운영체제 재시작: 포트가 여전히 해제되지 않을 경우, 운영체제를 재시작하면 포트가 해제됩니다. 이는 드물지만 효과적인 방법입니다.

표준 해결

1. 포트 사용 상태 확인: 다음 명령을 사용하여 포트 사용 상태를 확인합니다.

   // Mac/Linux
   lsof -i :3000
   
   // Windows
   netstat -ano | findstr :3000

2. 서버 종료 코드 구현: 서버가 종료될 때 포트를 해제하도록 코드를 추가합니다.

   process.on('SIGINT', () => {
     server.close(() => {
       console.log('Server closed');
       process.exit(0);
     });
   });

3. 환경 변수 사용: 포트를 환경 변수로 설정하여 유연성을 높입니다.

   const port = process.env.PORT || 3000;
   server.listen(port, '127.0.0.1', () => {
     console.log(`Server running at http://127.0.0.1:${port}/`);
   });

4. 포트 충돌 방지: 개발 시작 전에 포트 충돌을 방지하기 위해 항상 포트 사용 상태를 확인합니다.
5. 개발 도구 사용: nodemon과 같은 도구를 사용하여 서버를 자동으로 재시작하고 포트를 해제합니다.

고급 해결

1. 로드 밸런싱 설정: 포트 사용을 분산시키기 위해 로드 밸런서를 설정합니다. 이는 대규모 애플리케이션에서 유용합니다.
2. Docker 컨테이너 사용: 독립적인 환경에서 애플리케이션을 실행하여 포트 충돌을 방지합니다.
3. 클라우드 서비스 활용: 클라우드 서비스의 자동 포트 할당 기능을 사용하여 충돌을 방지합니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하는 방법은 다음과 같습니다:

• 포트 관리 자동화: 스크립트를 사용하여 포트 사용 상태를 자동으로 확인합니다.
• 개발 환경 분리: Docker와 같은 도구를 사용하여 개발 환경을 격리합니다.
• 정기적 코드 리뷰: 팀 코드 리뷰를 통해 서버 종료 코드가 올바르게 구현되었는지 확인합니다.
• 문서화: 팀 내 포트 사용 가이드를 문서화하여 공유합니다.

🎯 마무리 및 추가 팁

이 글에서는 ‘Error: listen EADDRINUSE’ 에러의 원인을 분석하고 다양한 해결책을 제공했습니다. 핵심적인 내용은 다음과 같습니다:

• 포트 충돌 문제를 빠르게 해결하기 위해 포트 사용 상태를 확인합니다.
• 포트 변경이나 운영체제 재시작을 통해 임시 해결이 가능합니다.
• Docker와 같은 도구를 사용하여 환경을 격리하면 포트 문제를 사전에 예방할 수 있습니다.

더 많은 정보를 원하신다면, Node.js 공식 문서나 관련 커뮤니티를 참고하세요. 비슷한 에러들이 궁금하시다면, ‘Error: listen EACCES’에 대한 글도 확인해보세요. 개발은 때때로 고단하지만, 이 글이 여러분의 문제 해결에 도움이 되었기를 바랍니다. 계속해서 성장해 나가시길 응원합니다!