ERR_CONNECTION_REFUSED 원인과 해결 체크리스트
웹사이트나 로컬 개발 서버에 접속했는데 ERR_CONNECTION_REFUSED가 표시되면 코드 문제인지 네트워크 문제인지부터 헷갈리기 쉽습니다. 특히 localhost에서 개발할 때 어제까지 정상적으로 열리던 주소가 갑자기 접속되지 않는 경우가 있는데요.
ERR_CONNECTION_REFUSED 오류는 브라우저가 대상 서버에 연결을 시도했지만 연결이 받아들여지지 않았을 때 볼 수 있는 메시지입니다.
서버 미실행부터 잘못된 포트, 방화벽, Docker 포트 설정까지 원인이 다양합니다. 가장 가능성이 높은 항목부터 확인해 보겠습니다.
ERR_CONNECTION_REFUSED 뜻은 무엇일까?
쉽게 표현하면 브라우저가 특정 주소와 포트로 연결을 요청했지만 그 연결을 받아줄 서비스가 없거나 연결이 거부된 상황이라고 이해하면 됩니다.
예를 들어 개발 서버가 3000번 포트에서 실행될 것으로 생각하고 접속했는데 실제 서버가 종료되어 있다면 정상적인 HTTP 응답 자체를 받을 수 없습니다.
http://localhost:3000
따라서 이 오류에서는 HTML이나 JavaScript 코드를 수정하기 전에 해당 주소에서 서버가 실제로 실행 중인지 확인하는 것이 우선입니다.
ERR_CONNECTION_REFUSED 원인 1, 서버가 실행되지 않은 경우
로컬 개발 환경에서 가장 먼저 확인할 부분입니다. React, Vite, Next.js 또는 Node.js 서버를 종료한 상태에서 기존 주소로 접속하면 연결할 프로세스가 없을 수 있습니다.
npm run dev
프로젝트에 따라 실제 실행 명령은 다를 수 있으므로 package.json의 scripts를 확인하세요. 명령을 실행한 뒤 터미널에 에러가 발생해 서버가 즉시 종료되지는 않았는지도 살펴봐야 합니다.
브라우저를 계속 새로고침하는 것보다 서버 터미널이 현재 실행 상태인지 확인하는 것이 훨씬 빠릅니다.
ERR_CONNECTION_REFUSED 원인 2, 포트 번호가 다른 경우
서버는 정상적으로 실행 중인데 브라우저에서 다른 포트로 접속하는 실수도 흔합니다.
// 서버가 실제 실행 중인 주소
http://localhost:5173
// 접속하려는 주소
http://localhost:3000
개발 도구가 빈 포트를 찾아 자동으로 다른 번호를 사용하는 경우도 있습니다. 따라서 평소 사용하던 포트를 기억해서 입력하기보다 서버를 시작했을 때 터미널에 출력되는 실제 주소를 확인하세요.
API 요청에서도 마찬가지입니다. 프론트엔드는 정상인데 API 서버의 포트만 틀렸다면 fetch 요청에서 네트워크 오류가 함께 나타날 수 있습니다.
localhost ERR_CONNECTION_REFUSED 원인 3, 서버가 중간에 종료된 경우
처음에는 서버가 실행됐지만 코드 오류나 설정 문제로 프로세스가 종료되는 경우도 있습니다. 이때 브라우저에서는 단순히 연결 거부만 보일 수 있어 원인을 놓치기 쉽습니다.
Node.js 서버라면 브라우저뿐 아니라 서버를 실행한 터미널을 확인하세요. SyntaxError, Cannot find module, 환경변수 누락 또는 포트 관련 오류가 먼저 출력됐을 수 있습니다.
ERR_CONNECTION_REFUSED가 최종 증상이고 실제 원인은 서버를 종료시킨 다른 오류일 수도 있습니다.
ERR_CONNECTION_REFUSED 원인 4, 잘못된 호스트 주소
localhost, 127.0.0.1, 내부 IP 또는 서버 도메인을 혼동하면 원하는 서비스에 연결하지 못할 수 있습니다. 특히 다른 PC나 스마트폰에서 개발 중인 컴퓨터의 localhost로 접속하려 할 때 주의해야 합니다.
localhost는 일반적으로 현재 요청을 보내는 기기 자신을 의미합니다. 따라서 스마트폰 브라우저에서 localhost를 입력한다고 해서 개발 PC의 서버로 연결되는 것은 아닙니다.
다른 기기에서 개발 서버에 접속해야 한다면 서버의 바인딩 설정과 네트워크 주소, 방화벽 등을 함께 확인해야 합니다.
ERR_CONNECTION_REFUSED 원인 5, 방화벽이나 보안 프로그램
서버와 포트가 정상인데 특정 환경에서만 접속되지 않는다면 운영체제 방화벽이나 보안 프로그램, 회사 네트워크 정책 등을 확인할 필요가 있습니다.
새 프로그램이나 서버 프로세스가 네트워크 연결을 수신하려 할 때 방화벽 설정의 영향을 받을 수 있습니다. 다른 컴퓨터에서는 접속되는데 특정 장치에서만 문제가 발생한다면 중요한 단서입니다.
다만 문제를 해결하기 위해 방화벽 전체를 무작정 끄기보다는 어떤 프로그램과 포트의 연결이 차단되고 있는지 먼저 확인하는 것이 안전합니다.
ERR_CONNECTION_REFUSED 원인 6, Docker 포트 연결 문제
Docker 컨테이너 안에서는 서버가 정상적으로 실행되고 있지만 호스트에 포트가 제대로 연결되지 않아 접속할 수 없는 경우도 있습니다.
docker run -p 8080:3000 my-app
이 예에서는 호스트의 8080번 포트를 컨테이너의 3000번 포트에 연결합니다. 컨테이너 내부 서버가 실제로 사용하는 포트와 매핑 대상이 다르면 원하는 서비스에 접속하지 못할 수 있습니다.
Docker 환경이라면 컨테이너 실행 상태 → 내부 서버 포트 → 호스트 포트 매핑 순서로 확인해 보세요.
ERR_CONNECTION_REFUSED 원인 7, 서버 바인딩 설정
서버가 어느 네트워크 인터페이스에서 연결을 받을 것인지도 영향을 줄 수 있습니다. 서버가 로컬 인터페이스에만 바인딩되어 있다면 같은 컴퓨터에서는 접속되지만 다른 장치에서는 접근하지 못할 수 있습니다.
반대로 외부 접속을 허용해야 하는 개발 환경이라면 사용하는 프레임워크의 host 설정을 확인해야 합니다. 이 설정은 개발 서버마다 방법이 다를 수 있으므로 해당 도구의 설정 방식에 맞게 적용해야 합니다.
외부 연결을 허용할 때는 편의성뿐 아니라 같은 네트워크의 다른 장치에 개발 서버가 노출될 수 있다는 점도 고려하세요.
ERR_CONNECTION_REFUSED 원인 8, 프록시 설정 문제
프론트엔드 개발 서버가 API 요청을 백엔드로 전달하도록 프록시를 설정했다면 실제 대상 서버 주소가 잘못되어 연결이 거부될 수 있습니다.
브라우저
↓
프론트엔드 개발 서버
↓
API 서버
이 경우 브라우저 주소는 정상적으로 열리지만 API 요청만 실패할 수도 있습니다. 프록시가 전달하려는 백엔드 서버의 호스트와 포트가 실제 실행 주소와 같은지 확인하세요.
백엔드 포트를 변경한 뒤 프록시 설정을 수정하지 않은 경우 쉽게 발생할 수 있습니다.
ERR_CONNECTION_REFUSED 주요 원인 한눈에 보기
| 증상 | 먼저 확인할 부분 |
|---|---|
| localhost 전체가 안 열림 | 개발 서버 실행 여부 |
| 서버는 켜져 있는데 접속 불가 | 호스트·포트 번호 |
| 실행 직후 접속이 끊김 | 서버 터미널의 실제 오류 |
| 다른 기기에서만 접속 불가 | 바인딩·IP·방화벽 |
| Docker에서만 발생 | 컨테이너와 포트 매핑 |
| API 요청만 실패 | 백엔드 서버·프록시 포트 |
| 특정 네트워크에서만 실패 | 방화벽·프록시·네트워크 정책 |
ERR_CONNECTION_REFUSED 해결 체크리스트
여러 설정을 한꺼번에 변경하기보다 아래 순서대로 확인하면 원인을 빠르게 좁힐 수 있습니다.
1. 주소와 포트 번호가 정확한지 확인합니다.
2. 서버 프로세스가 실제로 실행 중인지 확인합니다.
3. 서버 터미널에 먼저 발생한 오류가 없는지 확인합니다.
4. 프론트엔드와 API 서버의 포트를 각각 확인합니다.
5. localhost와 외부 IP를 혼동하지 않았는지 확인합니다.
6. 서버의 host·binding 설정을 점검합니다.
7. 방화벽이나 프록시의 영향을 확인합니다.
8. Docker라면 컨테이너 실행 상태와 포트 매핑을 확인합니다.
9. 배포 서버라면 서비스 프로세스가 정상인지 확인합니다.
10. 수정 후 서버를 재시작하고 다시 접속합니다.
Failed to fetch와 ERR_CONNECTION_REFUSED 차이는?
앞서 살펴본 Failed to fetch는 JavaScript의 fetch 요청이 정상적으로 완료되지 않았을 때 볼 수 있는 비교적 넓은 범위의 메시지입니다. CORS, 네트워크, DNS, HTTPS 등 여러 원인이 포함될 수 있습니다.
반면 ERR_CONNECTION_REFUSED가 함께 확인된다면 요청 대상과의 연결 자체가 거부된 상황을 우선 의심할 수 있습니다. 이때는 CORS 헤더를 수정하기 전에 서버가 해당 주소와 포트에서 실제로 연결을 받고 있는지부터 확인하는 편이 좋습니다.
ERR_CONNECTION_REFUSED인데 CORS 설정만 계속 변경하는 것은 해결 방향이 어긋날 수 있습니다. 서버에 연결조차 되지 않는다면 먼저 연결 문제를 해결해야 합니다.
ERR_CONNECTION_REFUSED 가장 쉬운 해결 방법
ERR_CONNECTION_REFUSED 오류를 만났다면 가장 먼저 브라우저 캐시를 삭제하거나 코드를 수정할 필요는 없습니다. 주소 확인 → 서버 실행 확인 → 포트 확인 이 세 가지부터 점검하세요.
localhost에서 발생했다면 개발 서버를 실행한 터미널을 열어 현재 프로세스가 살아 있는지와 실제 접속 주소가 무엇인지 확인합니다. 외부 서버라면 서버 프로세스와 네트워크·방화벽 설정까지 범위를 넓혀보세요.
정리하면 서버 → 주소 → 포트 → 터미널 로그 → 바인딩 → 방화벽·Docker 순서로 확인하면 됩니다. 연결 자체의 문제와 CORS·HTTP 오류를 구분할 수 있다면 ERR_CONNECTION_REFUSED도 훨씬 빠르게 해결할 수 있습니다.