Python “ConnectionError: [Errno 111] Connection refused”란?
ConnectionError: [Errno 111] Connection refused는 Python의 socket이나 requests 같은 네트워킹 라이브러리를 사용하여 원격 서버에 연결을 시도할 때, 대상 서버가 연결 요청을 거부했음을 나타내는 오류입니다. 숫자 111은 Linux 시스템에서 “Connection refused”를 의미하는 에러 코드입니다. (Windows나 다른 OS에서는 다른 에러 코드가 표시될 수 있습니다.)
이 오류는 클라이언트 측 코드의 문제라기보다는, 서버가 클라이언트의 연결을 받아들일 준비가 되어 있지 않다는 신호입니다.
“Connection refused”의 일반적인 원인
- 서버가 실행 중이 아님: 가장 흔한 원인입니다. 연결하려는 IP 주소와 포트에서 아무런 애플리케이션도 실행되고 있지 않을 수 있습니다.
- 잘못된 IP 주소 또는 포트: 서버는 실행 중이지만, 클라이언트가 잘못된 IP 주소나 포트 번호로 연결을 시도하고 있을 수 있습니다.
- 방화벽: 서버 또는 클라이언트, 혹은 그 사이의 네트워크 장비(라우터 등)에 있는 방화벽이 특정 포트로의 연결을 차단하고 있을 수 있습니다.
- 서버의 리스닝(Listening) 주소 설정 오류: 서버 애플리케이션이
localhost또는127.0.0.1로만 바인딩되어 있을 수 있습니다. 이 경우, 서버가 실행 중인 컴퓨터 내부에서는 접속이 가능하지만 다른 컴퓨터에서는 접속할 수 없습니다. 외부에서의 접속을 허용하려면0.0.0.0으로 바인딩해야 합니다. - 서버의 연결 대기 큐(Backlog) 초과: 서버가 동시에 처리할 수 있는 연결 요청의 한계를 초과하여 새로운 연결을 거부하는 경우입니다. 이는 서버 부하가 매우 높을 때 발생할 수 있습니다.
“Connection refused” 해결 방법
1. 서버 상태 확인
가장 먼저 연결하려는 서버가 정상적으로 실행 중인지 확인해야 합니다.
- 서버에 직접 접근할 수 있다면, 해당 애플리케이션의 프로세스가 실행 중인지 확인합니다.
- 서버 로그를 확인하여 시작 시 오류가 발생하지 않았는지 점검합니다.
2. IP 주소 및 포트 확인
클라이언트 코드에 하드코딩된 IP 주소와 포트가 서버가 리스닝하고 있는 주소 및 포트와 일치하는지 다시 한번 확인하세요.
서버 측에서 netstat 명령어를 사용하면 어떤 포트에서 리스닝 중인지 확인할 수 있습니다.
# Linux/macOS
netstat -an | grep LISTEN
# Windows
netstat -an | findstr "LISTENING"
3. 방화벽 설정 확인
서버의 방화벽이 클라이언트의 연결을 허용하도록 설정되어 있는지 확인합니다. 예를 들어, Linux의 ufw나 firewalld, Windows의 방화벽 설정에서 해당 포트(예: 8080)가 인바운드 규칙에 허용되어 있는지 확인해야 합니다.
클라이언트 측에서도 아웃바운드 연결이 차단되지 않았는지 확인이 필요할 수 있습니다.
4. 서버 리스닝 주소 확인
서버 애플리케이션이 모든 네트워크 인터페이스로부터의 연결을 허용하는지 확인하세요. 일반적으로 웹 서버나 API 서버를 설정할 때 호스트 주소를 127.0.0.1이 아닌 0.0.0.0으로 설정해야 외부에서 접속할 수 있습니다.
Flask 예제:
# 127.0.0.1 (localhost)에서만 접속 가능
# app.run(host='127.0.0.1', port=5000)
# 모든 IP 주소에서 접속 가능
app.run(host='0.0.0.0', port=5000)
5. 간단한 연결 테스트
telnet이나 nc (netcat) 같은 간단한 도구를 사용하여 클라이언트 컴퓨터에서 서버로의 기본적인 TCP 연결이 가능한지 테스트할 수 있습니다.
telnet <server_ip> <port>
# 예: telnet 192.168.1.100 8080
만약 여기서도 “Connection refused”가 발생한다면, Python 코드의 문제가 아니라 네트워크 또는 서버 설정의 문제임이 확실합니다.
결론
ConnectionError: [Errno 111] Connection refused는 네트워크 프로그래밍에서 흔히 마주치는 문제이며, 대부분의 경우 클라이언트 코드보다는 서버 측의 상태나 네트워크 구성에 원인이 있습니다. 문제를 해결하기 위해서는 서버가 정상적으로 실행 중인지, 올바른 주소와 포트로 리스닝하고 있는지, 그리고 방화벽이 연결을 막고 있지는 않은지 체계적으로 확인하는 접근 방식이 필요합니다.
전문 보완 체크
Python “ConnectionError: [Errno 111] Connection refused” 해결 방법에서 중요한 기준은 독자가 한 번 따라 해서 성공했는지가 아닙니다. 이 주제는 재현 가능한 디버깅 절차로 다루는 편이 안전합니다. 결론을 내리기 전에 실행 환경, 정확한 오류 경계, 최소 재현 예제, 되돌릴 수 있는 경로를 확인해야 합니다. 또한 나중에 같은 문제가 반복될 수 있으므로, 관찰한 사실과 사용한 가정, 결론이 바뀔 조건을 짧은 결정 기록으로 남기는 것이 좋습니다.
신뢰도를 높이는 증거
작업을 바꾸기 전에는 객관적인 증거를 먼저 확인해야 합니다. 쓸 만한 증거에는 전체 명령 출력, 버전 번호, 변경된 파일, 기대 동작과 실제 동작가 포함됩니다. 증거가 서로 맞지 않으면 억지로 하나의 이야기로 합치지 말고 충돌 자체를 남겨야 합니다. 빠른 해결이 한 번 성공했더라도 같은 입력, 계정, 의존성, 기기 상태에서 다시 확인하지 않았다면 아직 확정된 해결책이라고 보기 어렵습니다.
검토 표
| 검토 항목 | 확인할 내용 | 중요한 이유 |
|---|---|---|
| 범위 | 이 글이 다루는 정확한 사례 | 조언을 과도하게 적용하지 않게 합니다 |
| 기준 상태 | 변경 전 상태 | 되돌리기와 비교를 가능하게 합니다 |
| 변경 | 실제로 수행한 가장 작은 조치 | 숨은 부작용을 줄입니다 |
| 결과 | 변경 뒤 관찰한 출력 또는 반응 | 기대와 증거를 구분합니다 |
| 재확인 | 결론을 다시 볼 시점 | 글의 정확도를 유지합니다 |
예외 상황과 실패 모드
주요 위험은 증상만 고치고 원인을 남기는 상황, 서로 무관한 변경을 같은 테스트에 섞는 상황입니다. 생산 데이터, 개인정보, 돈, 건강, 법적 권리, 보안 복구가 관련되어 있다면 넓은 해결책을 바로 적용하기보다 먼저 증거를 모으는 보수적인 접근이 낫습니다. 같은 제목의 문제라도 환경이 다르면 원인이 달라질 수 있으므로, 독자는 명령이나 결정을 복사하기 전에 자신의 조건이 글의 가정과 맞는지 비교해야 합니다.
유지보수 기준
이 안내는 의존성, 운영체제, 빌드 도구가 바뀐 뒤 다시 확인해야 합니다. 좋은 업데이트는 글 전체를 다시 쓰는 것이 아니라 예시, 링크, 명령, 화면, 판단 기준이 현재 동작과 여전히 맞는지 확인하는 일입니다. 기존 결론이 유효하면 확인 날짜를 남기고, 바뀌었다면 무엇이 바뀌었고 왜 이전 조언만으로 부족한지 설명해야 합니다.
실행 전 질문
- 문제나 판단이 실제임을 보여 주는 가장 작은 관찰 신호는 무엇인가?
- 공식 출처는 무엇이고, 내부 판단은 어느 부분인가?
- 변경 전에 반드시 캡처해야 할 기록은 무엇인가?
- 어떤 결과가 나오면 이 글의 조언이 맞지 않는다고 볼 것인가?
- 같은 문제가 반복될 때 누가 이 기록을 다시 봐야 하는가?
함께 보면 좋은 글
같은 주제 흐름에서 이어서 읽기 좋은 글입니다.
Leave a comment