파이썬으로 API 호출하는 스크립트를 돌리다가 갑자기 NewConnectionError가 뜨면서 죽어버린 경험, 한 번쯤 있으실 겁니다. 어제까지 잘 되던 코드가 오늘 갑자기 연결을 못 잡는 경우도 많아서 원인을 짚기가 애매합니다. 실제로는 몇 가지 패턴으로 좁혀지기 때문에 순서대로 확인해보면 금방 해결됩니다.
NewConnectionError는 urllib3(requests 내부 라이브러리)가 대상 서버에 소켓 연결 자체를 맺지 못했을 때 발생합니다. 원인은 대부분 잘못된 호스트 주소, 방화벽/프록시 차단, DNS 조회 실패 셋 중 하나입니다. 네트워크 상태와 URL을 먼저 확인한 뒤 코드 설정을 손보는 순서로 접근해야 합니다.
NewConnectionError란 무엇인가
이 에러는 requests 라이브러리 안에서 실제 HTTP 통신을 담당하는 urllib3가 소켓 연결 단계에서 실패했을 때 던지는 예외입니다. 에러 메시지를 보면 보통 이런 식으로 출력됩니다.
urllib3.exceptions.NewConnectionError: Failed to establish a new connection: [Errno 111] Connection refused
실무에서 보면 이 에러가 뜨는 시점에 서버 응답 자체를 받은 게 아니라, 연결 시도 단계에서 이미 막혔다는 게 핵심입니다. 그래서 요청 헤더나 파라미터를 아무리 고쳐봐야 소용없는 경우가 많습니다.
가장 많이 발생하는 원인 4가지
이건 직접 겪어보면 체감되는데, 원인을 하나씩 소거해가는 방식이 가장 빠릅니다. 아래 순서대로 확인해보시길 권합니다.
- 호스트 주소 오타 또는 잘못된 포트 번호 — URL 한 글자만 틀려도 발생합니다
- 인터넷 연결 자체가 끊긴 경우 — Wi-Fi나 사내망 연결 상태 확인 필요
- 방화벽 또는 프록시가 요청을 차단하는 경우 — 회사·학교 네트워크에서 자주 발생
- DNS 조회 실패 — 도메인 이름을 IP로 변환하지 못하는 상태
많이들 여기서 막히더라고요. 코드 자체는 멀쩡한데 회사 네트워크로 옮기자마자 에러가 나는 경우, 90% 이상은 방화벽이나 프록시 설정 문제입니다.
단계별 해결 방법
원인별로 확인 순서를 정리하면 아래와 같습니다.
- URL 주소를 브라우저에 그대로 붙여넣어 접속되는지 먼저 확인한다
- 터미널에서 ping 대상도메인 또는 nslookup 대상도메인으로 DNS 조회가 되는지 확인한다
- 사내망이나 VPN 환경이라면 프록시 설정이 필요한지 확인한다
- requests 코드에 프록시를 명시적으로 지정해본다
- 타임아웃 값을 늘리고 재시도(Retry) 로직을 추가한다
프록시가 필요한 환경이라면 아래처럼 명시적으로 지정해줘야 합니다.
proxies = {“http”: “http://프록시주소:포트”, “https”: “http://프록시주소:포트”}
requests.get(url, proxies=proxies, timeout=10)
이 부분이 핵심입니다. 재시도 로직 없이 단발성 요청만 날리면 서버가 순간적으로 응답이 늦어졌을 때도 바로 에러로 떨어집니다. urllib3의 Retry 객체를 붙여주면 일시적인 네트워크 지연은 자동으로 몇 번 더 시도한 뒤에야 실패로 처리됩니다.
실무 팁 — Docker 컨테이너 안에서 스크립트를 돌릴 때 localhost로 요청을 보내면 컨테이너 자신을 가리키기 때문에 NewConnectionError가 뜹니다. 호스트 머신의 서비스를 호출해야 한다면 host.docker.internal이나 컨테이너 네트워크 설정을 먼저 확인하세요.
비슷한 에러와 헷갈리지 않도록 비교
NewConnectionError 말고도 비슷하게 생긴 예외가 여럿 있어서 원인 파악이 헷갈릴 수 있습니다.
| 예외 종류 | 발생 시점 | 주요 원인 |
|---|---|---|
| NewConnectionError | 연결 시도 단계 | 잘못된 주소, 방화벽 차단, DNS 실패 |
| ConnectionError | 연결 중 끊김 | 서버가 중간에 연결을 끊거나 재설정 |
| Timeout | 응답 대기 중 | 서버 응답이 지정 시간 내에 오지 않음 |
| SSLError | TLS 핸드셰이크 단계 | 인증서 오류, 프로토콜 불일치 |
NewConnectionError는 이 중에서도 가장 앞 단계, 즉 소켓 자체를 열지 못한 경우에만 발생한다는 점이 다릅니다. 그래서 SSL 인증서를 재발급하거나 타임아웃 값을 늘리는 식의 해결책은 이 에러에는 대부분 효과가 없습니다.
체크리스트와 흔한 오해 바로잡기
- URL 주소와 포트 번호를 다시 한번 확인했는가
- 브라우저로 같은 주소에 접속이 되는지 테스트했는가
- ping 또는 nslookup으로 DNS 조회가 정상인지 확인했는가
- 사내망·VPN 환경에서 프록시 설정이 필요한지 확인했는가
- Docker나 가상환경 안에서 실행 중이라면 네트워크 구성을 확인했는가
- requests, urllib3 라이브러리 버전이 최신인지 확인했는가
❌ “타임아웃 값을 늘리면 해결된다” → ⭕ NewConnectionError는 연결 자체가 안 되는 상황이라 타임아웃을 늘려도 결과는 같습니다. 타임아웃 조정은 Timeout 예외에만 유효합니다.
❌ “라이브러리를 재설치하면 무조건 고쳐진다” → ⭕ 코드나 라이브러리 문제가 아니라 네트워크 경로 자체가 막힌 경우가 대부분이라, 재설치보다 네트워크 확인이 먼저입니다.
초보자와 실무자의 접근 차이
초보자는 에러 메시지만 보고 바로 코드를 뜯어고치려는 경향이 있습니다. requests 옵션을 이것저것 바꿔보다가 결국 원인을 못 찾고 스택오버플로우 코드를 그대로 복사해오는 경우도 흔합니다.
실무자는 반대로 코드보다 네트워크 경로부터 확인합니다. 같은 URL을 curl이나 브라우저로 먼저 찔러보고, 거기서도 안 되면 코드 문제가 아니라는 걸 빠르게 판단합니다. 왜 이 방식이 실제로 더 잘 먹히는지는 명확합니다. NewConnectionError 자체가 애플리케이션 계층이 아니라 네트워크 계층 문제인 경우가 대부분이기 때문에, 코드를 고치는 것보다 경로를 확인하는 게 원인 파악 속도를 훨씬 앞당깁니다.
지금 스크립트가 에러를 내고 있다면, 코드를 고치기 전에 같은 URL을 터미널에서 curl로 한번 찔러보셨나요?
지금 바로 해볼 일은 하나입니다. 터미널에서 curl -v 대상URL을 실행해 연결이 되는지부터 확인해보세요. 여기서 막힌다면 코드 문제가 아니라 네트워크 문제입니다.
이 에러 어떤 환경에서 만나셨나요? 사내망, 개인 서버, 클라우드 환경 중 어디였는지 댓글로 알려주시면 사례별로 더 정리해보겠습니다. 혹시 프록시 설정으로 해결하신 경험 있으신가요?
다음 글로는 requests Timeout 에러 해결방법, Docker 컨테이너 네트워크 설정 가이드를 추천드립니다.
본 포스팅은 정보 전달 목적이며, 실제 적용 시 발생하는 책임은 사용자에게 있습니다.