Next.js EADDRINUSE 해결, 3000번 포트 확인 순서

npm run dev를 눌렀는데 Next.js 앱이 켜지지 않고 EADDRINUSE나 address already in use :::3000이 보이면, 먼저 코드가 망가졌다고 판단하지 않아도 됩니다. 대부분은 3000번 포트를 이미 다른 개발 서버가 쓰고 있다는 뜻입니다. 지금 필요한 일은 코드 수정이 아니라 포트 주인을 찾는 일입니다.

Next.js 개발 서버의 3000번 포트 충돌에서 PID 확인과 대체 포트 실행으로 나뉘는 흐름

Node.js 공식 오류 문서는 EADDRINUSE를 로컬의 다른 서버가 같은 주소를 점유해 바인딩하지 못한 상태로 설명합니다. 이 말은 Next.js 코드의 문법 문제가 아니라, 실행하려는 서버 주소가 이미 점유된 상태일 수 있다는 뜻입니다. Next.js CLI 문서도 next dev의 기본 포트가 3000번이고 -p, --port <port>로 포트를 지정할 수 있다고 안내합니다. 그래서 첫 대응은 단순합니다. 3000번을 누가 쓰는지 보고, 끌지 바꿀지 고릅니다.

오류 문장에서 포트 번호를 먼저 떼어 냅니다

터미널에서 먼저 볼 단어는 세 가지입니다.

EADDRINUSE
address already in use
3000

3000 대신 3001, 5173, 8080이 나올 수도 있습니다. 중요한 것은 포트 번호입니다. AI에게 바로 "고쳐 줘"라고 보내면 앱 구조를 다시 만지려 할 수 있습니다. 반대로 포트 번호를 잡아 주면 질문 범위가 작아집니다.

초보자가 붙여 넣기 좋은 첫 질문은 이 정도면 충분합니다.

Next.js 앱을 npm run dev로 켰는데 EADDRINUSE 오류가 납니다.
오류에 나온 포트는 3000입니다.
코드 전체를 바꾸지 말고 포트 충돌인지 확인하는 순서만 알려 주세요.
윈도우 기준 명령으로 설명해 주세요.

여기서 아직 어떤 프로세스도 종료하지 않습니다. 포트를 쓰는 프로세스를 확인한 뒤에만 종료 여부를 정합니다.

netstat로 3000번을 잡은 PID를 찾습니다

윈도우에서는 netstat로 특정 포트를 쓰는 프로세스 ID를 확인할 수 있습니다. learn.microsoft.com의 netstat 문서는 네트워크 연결과 관련 정보를 보여 주는 명령으로 설명하고, 옵션을 이용해 프로세스 ID까지 확인할 수 있게 합니다.

PowerShell이나 명령 프롬프트에서 아래처럼 입력합니다.

netstat -ano | findstr :3000

결과가 이런 모양이면 맨 오른쪽 숫자가 PID입니다.

TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    12345

이때 12345가 지금 3000번 포트를 잡고 있는 프로세스입니다. 결과가 여러 줄이면 LISTENING인 줄을 먼저 봅니다. 결과가 아예 없다면 포트 충돌이 이미 풀렸거나, 오류에 나온 포트 번호가 3000번이 아닐 수 있습니다.

Next.js 포트 충돌을 찾는 확인표로 netstat와 tasklist, 대체 포트 실행 순서를 정리한 화면

PID의 정체를 보고 종료 여부를 고릅니다

PID만 보고 바로 종료하면 안 됩니다. 같은 3000번을 쓰는 프로세스가 이전에 켜 둔 Next.js dev 서버일 수도 있지만, 다른 작업용 서버일 수도 있습니다. learn.microsoft.com의 tasklist 문서는 실행 중인 프로세스 목록과 PID를 확인하는 명령을 제공합니다.

방금 본 PID가 12345라면 이렇게 확인합니다.

tasklist /FI "PID eq 12345"

결과가 node.exe이고, 조금 전 켜 둔 개발 서버가 남아 있다고 판단되면 종료를 선택할 수 있습니다. Microsoft Learn의 taskkill 문서는 PID를 기준으로 프로세스를 종료할 수 있다고 설명합니다.

taskkill /PID 12345 /F

다만 프로세스 이름이 낯설거나, 회사 장비에서 어떤 서비스인지 모르겠다면 종료하지 않는 편이 안전합니다. 이때는 프로세스를 죽이지 말고 다른 포트로 실행합니다.

npm run dev -- -p 3001

Next.js CLI에서 -p는 실행 포트를 지정하는 옵션입니다. 프로젝트의 package.json이 next dev를 실행하도록 되어 있다면 위 명령은 Next.js dev 서버를 3001번에서 열게 합니다.

상황	선택
이전에 켜 둔 내 Next.js 서버가 확실함	PID 종료 후 다시 `npm run dev`
어떤 프로세스인지 모르겠음	`npm run dev -- -p 3001`
같은 오류가 3001에서도 반복됨	오류에 나온 새 포트로 다시 확인

AI에게 증거 네 줄만 넘깁니다

포트 충돌은 AI에게 맡길 때도 정보가 작아야 잘 풀립니다. "앱이 안 돼요"라고 보내면 AI는 라우팅, 컴포넌트, 패키지, 설정 파일을 넓게 건드릴 수 있습니다. 대신 아래 네 줄을 채워 보냅니다.

AI에게 Next.js 포트 충돌을 물어볼 때 오류와 PID, 원하는 해결을 적는 네 줄 입력 카드

오류 메시지: EADDRINUSE address already in use :::3000
확인 명령: netstat -ano | findstr :3000
PID 결과: 12345, tasklist 결과는 node.exe
원하는 해결: 이전 서버를 종료할지 3001번으로 바꿀지 판단해 주세요

이렇게 보내면 AI가 바꿔야 할 범위가 좁아집니다. 파일 전체 재작성보다 실행 상태 정리가 먼저라는 점도 분명해집니다.

포트 충돌이 아닌 경우를 구분합니다

EADDRINUSE가 사라졌는데도 화면이 안 뜨면 그때부터는 다른 문제를 봅니다. Module not found가 보이면 설치 문제와 경로 문제를 나누는 순서를, Hydration failed가 보이면 서버와 브라우저의 첫 화면 차이를 찾는 순서를 사용하세요. 환경변수 undefined도 포트 충돌과 다른 범주입니다. 이 글의 순서는 dev 서버가 시작조차 못 하고 포트 오류에서 멈출 때만 씁니다.

확인 순서는 아래처럼 끝냅니다.

오류에 EADDRINUSE가 있는지 본다.
오류에 나온 포트 번호를 적는다.
netstat로 PID를 찾는다.
tasklist로 PID의 정체를 확인한다.
안전하면 종료하고, 모르면 다른 포트로 실행한다.

이 다섯 줄을 채운 뒤에도 앱이 안 뜬다면 포트 문제는 거의 정리된 상태입니다. 그때 AI에게 다음 오류 전문을 다시 붙여 넣는 편이 좋습니다. 오늘 목표는 앱 전체를 다시 만드는 것이 아니라, Next.js dev 서버가 열릴 자리부터 비우는 것입니다.

공식 확인 링크

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.

Next.js EADDRINUSE, 3000번 포트 주인을 확인하고 다시 여는 순서