🧩 FastAPI + MongoDB Atlas 연동 에러 해결기 (SSL handshake failed)

FastAPI를 공부하며 MongoDB Atlas와 연동하는 과정에서, 환경 차이로 발생한 에러를 겪었고 이를 해결한 과정을 정리해봤습니다.

환경 차이에서 오는 문제는 언제나 예상 밖에서 발생하죠...!
해결까지 2시간이나 걸렸지만, 성장통이라 생각하며 기록해봅니다.

🖥️ 환경 정보

구분	내용
노트북	Python 3.11.9, FastAPI + MongoDB Atlas 연동 성공
데스크탑	Python 3.12.10, 동일한 코드 실행 → 에러 발생

🧨 발생한 에러

SSL handshake failed: tlsv1 alert internal error
pymongo.errors.ServerSelectionTimeoutError

요약:
FastAPI(클라이언트)에서 MongoDB Atlas 서버와 보안 연결(SSL) 을 시도했지만, handshake 실패로 연결이 안 되는 문제였습니다.

🔍 원인 분석 & 점검 사항

문제 해결을 위해 검색하면서 발생 할 수 있는 원인을 찾아봤습니다.

1. Python TLS/SSL 미지원 ❌

MongoDB Atlas는 TLS 1.2 이상을 요구합니다.
Python 3.6 이하나 구버전 OpenSSL을 사용하는 경우 문제가 생길 수 있다고 해요.

✅ Python 3.12.10 사용 중 → 해당 사항 없음

2. MongoDB URI 오류 ❌

연결 문자열(MongoDB URI)이 잘못되었을 수도 있다는 이야기를 봤습니다.

✅ 동일한 URI를 노트북에서 잘 사용했음 → 문제 없음

3. 방화벽 / 네트워크 문제 ✅

검색 중 Atlas의 IP 접근 허용 설정(Network Access) 을 체크해보라는 글을 발견했습니다.

MongoDB Atlas에서는 기본적으로 특정 IP만 접근을 허용합니다.
내 데스크탑이 허용된 IP가 아니었다는 것!

✅ 해결 방법: MongoDB Atlas에서 모든 IP 허용하기
개발 중이라면 간단히 모든 IP를 허용하는 설정으로 해결할 수 있어요.

설정 방법:

1. MongoDB Atlas 접속
   👉 https://cloud.mongodb.com

2. 연결할 Project 선택

3. 왼쪽 메뉴 → Network Access 클릭
   (사이드바 > SECURITY 섹션 안에 있음)

4. IP Access List 탭에서
   ➕ ADD IP ADDRESS 클릭

아래처럼 입력

5. Whitelist Entry: 0.0.0.0/0

6. Comment: "Allow all IPs" (선택)

✅ Confirm 버튼 클릭

⚠️ 보안상 운영 환경에서는 자신의 IP만 허용하는 게 좋습니다.
지금은 개발용이니 편하게 설정!

🎉 결론

방화벽 설정 문제였고, 해결은 생각보다 간단했어요.
하지만 2시간 동안 삽질한 끝에 얻은 값진 경험!

✍️ 마무리

FastAPI, MongoDB Atlas 연결 시 Network Access 설정 필수 확인!

처음 겪는 SSL handshake 에러는 당황스럽지만, 차근히 원인을 좁혀가면 해결 가능해요.

이젠 어떤 환경에서든 MongoDB 연동 자신 있습니다 💪