502 Bad Gateway

증상

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

확인

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

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

Nginx에서 502가 보일 때

Nginx가 오류 화면을 반환했다면 먼저 적용 중인 업스트림 주소와 같은 시각의 로그를 비교합니다. 502만 보고 Nginx, 애플리케이션, PHP-FPM 중 하나를 원인으로 정하지 않습니다.

1. 적용 중인 설정을 확인합니다

운영 서버에서 아래 명령을 실행할 권한이 있다면 설정을 변경하지 않고 결과만 확인합니다.

nginx -T

nginx -T는 설정 문법을 검사하고 Nginx가 읽은 설정을 출력합니다. 결과에서 오류가 난 server·location의 proxy_pass 또는 fastcgi_pass 대상 주소를 확인합니다. 출력에 인증 정보나 내부 주소가 포함될 수 있으므로 원문 전체를 외부에 게시하지 않습니다.

PHP-FPM을 사용한다면 Nginx의 fastcgi_pass 대상과 PHP-FPM pool의 listen 값을 비교합니다. 한쪽이 TCP 주소와 포트를 사용하고 다른 쪽이 Unix 도메인 소켓을 사용하거나, 소켓 경로가 다르면 같은 대상을 가리키지 않습니다. Unix 도메인 소켓이면 웹 서버 프로세스가 접근할 수 있도록 설정된 listen.owner, listen.group, listen.mode도 함께 기록합니다.

2. 업스트림 관찰값을 같은 요청으로 묶습니다

Nginx는 다음 값을 접근 로그 형식에 기록할 수 있습니다.

현재 로그에 이 값이 없다면 장애 중에 즉시 형식을 바꾸지 말고, 기존 오류 로그와 접근 로그에서 전체 URL·발생 시각·요청 식별자를 먼저 맞춥니다. 로그 형식 변경은 별도의 검토와 재현 계획을 세운 뒤 적용합니다.

3. 관찰 결과에 따라 다음 확인 대상을 정합니다

설정을 수정하기로 했다면 먼저 다음 명령으로 문법과 참조 파일을 검사합니다.

nginx -t

검사가 통과했다는 사실은 업스트림 주소와 애플리케이션 상태가 정상이라는 뜻이 아닙니다. 설정 적용 전후에 같은 URL과 로그 값을 비교해야 합니다.

재확인

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

주의

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

관찰값 기록

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

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

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

판정 기준

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

안전한 다음 확인

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