HTTP 502: Bad gateway

증상

브라우저 또는 HTTP 클라이언트에 502 Bad Gateway가 표시됩니다. 이 코드는 프록시·게이트웨이·로드 밸런서가 업스트림 서버에서 유효하지 않은 응답을 받은 상태를 뜻합니다.

확인

1. 오류가 난 전체 URL, 발생 시각, 응답 헤더를 기록합니다.
2. Cloudflare를 쓴다면 오류 화면에 Cloudflare 브랜딩이 있는지 확인합니다.
3. 프록시 또는 로드 밸런서와 원본 서버에서 같은 시각의 로그를 확인합니다.

Cloudflare 브랜딩이 있으면 원본 서버가 표준 502를 반환한 경우입니다. 브랜딩이 없는 빈 오류 화면이면 Cloudflare에서 발생한 오류일 수 있습니다. 두 경우의 담당 영역이 다르므로 화면을 먼저 구분합니다.

재확인

업스트림 응답 또는 프록시 설정에서 확인한 한 항목만 수정한 뒤 같은 URL을 다시 요청합니다. 가능하면 프록시를 거치지 않은 요청과 경유 요청의 결과도 비교합니다.

주의

502만으로 특정 언어·CMS·호스팅의 원인을 단정하지 마세요. 로그 확인 없이 프록시 설정, 헤더, 리다이렉트, 서버 구성을 한 번에 바꾸지 않습니다.

관찰값 기록

문제가 발생한 URL 또는 화면, 표시 시각, 운영 환경과 최근 변경 사항을 먼저 기록합니다. 화면이나 로그에 오류 문구가 일부만 보이면 앞뒤 문장을 보존하고 비밀번호·토큰·쿠키·개인정보는 가립니다.

다음 항목을 실제 값과 함께 확인합니다.

1. 오류 화면 또는 HTTP 응답에 502 Bad Gateway가 표시되는지 확인하고, 전체 URL·발생 시각·응답 헤더를 기록합니다.
2. Cloudflare를 쓰는 사이트라면 Cloudflare 브랜딩 유무를 확인합니다. 브랜딩이 있으면 원본 서버가 표준 502를 반환한 경우이며, 브랜딩이 없는 빈 오류 화면이면 Cloudflare에서 발생한 오류일 수 있습니다.
3. 프록시 또는 로드 밸런서와 원본 서버의 같은 시각 로그에서 업스트림 연결·응답 형식·원본 서버 오류를 확인합니다.
4. 한 항목을 수정했다면 같은 URL을 다시 요청해 502가 사라졌는지, 프록시를 거치지 않은 요청과 결과가 다른지 확인합니다.

판정 기준

오류 문구가 일치해도 같은 원인이 확정되는 것은 아닙니다. 웹서버·런타임·운영체제·플랫폼과 최근 변경 사항을 비교하고, 기대한 관찰값이 나오지 않으면 다음 단계로 넘어가지 않습니다. 이 문서는 출처가 확인한 범위만 설명하며, 범위를 벗어난 원인과 조치는 단정하지 않습니다.

안전한 다음 확인

설정·권한·데이터를 변경하기 전에 백업과 되돌리기 방법을 기록합니다. 운영 환경의 방화벽 전체 해제, 인증서 검증 우회, 데이터 삭제, 비밀값 공개를 기본 조치로 사용하지 않습니다. 확인 결과가 문서의 조건과 다르면 관련 Platform·Component 문서와 공식 출처를 먼저 확인합니다.