Nginx62�는 리버스 프록시로 쓰다 보면 피할 수 없는 에러가 502다.
502 Bad Gateway
nginx/1.x.x사용자한테 이게 보이는 순간 장애다. 빠르게 원인 찾고 고쳐야 하는데, 502는 원인이 한두 가지가 아니다. 이 글에서 발생 빈도 높은 원인과 해결책을 순서대로 정리한다.
1. 502 Bad Gateway는 뭔가
Nginx가 업스트림 서버(백엔드 앱, WAS, API 서버)에 요청을 넘겼는데 제대로 된 응답을 못 받았을 때 클라이언트에게 돌려주는 응답이다.
즉, Nginx 자체의 문제가 아니라 Nginx 뒤에 있는 서버의 문제다.
2. 원인별 분류 및 해결
원인 1: 업스트림 서버가 꺼져 있다 (가장 흔함)
에러 로그:
2026/06/26 10:00:00 [error] 12345#0: *1 connect() failed (111: Connection refused)
while connecting to upstream, upstream: "http://127.0.0.1:8080/api/health"Connection refused가 보이면 백엔드 앱이 죽은 거다.
# 프로세스 확인
ps aux | grep java
ps aux | grep node
ps aux | grep gunicorn
# 포트 리스닝 확인
ss -tlnp | grep 8080프로세스가 없으면 앱을 재시작한다. 재시작 후에도 바로 죽는다면 앱 자체의 에러 로그를 봐야 한다.
원인 2: 타임아웃
에러 로그:
upstream timed out (110: Operation timed out) while reading response header from upstream백엔드가 살아있긴 한데 응답이 너무 느린 경우다. Nginx의 기본 타임아웃값(60초)을 넘기면 이 에러가 발생한다.
# nginx.conf 또는 서버 블록
location / {
proxy_pass http://localhost:8080;
proxy_connect_timeout 60s; # 연결 타임아웃
proxy_send_timeout 60s; # 요청 전송 타임아웃
proxy_read_timeout 120s; # 응답 수신 타임아웃 (이걸 늘리면 됨)
}배치 작업이나 파일 업로드처럼 처리 시간이 긴 요청은 proxy_read_timeout을 요청 성격에 맞게 올린다. 무작정 크게 올리는 건 좋지 않고, 실제 처리 시간 + 여유분 정도로 설정한다.
원인 3: 업스트림 헤더가 너무 크다
에러 로그:
upstream sent too big header while reading response header from upstream백엔드 응답의 HTTP 헤더가 Nginx 버퍼 크기를 초과한 경우다. 쿠키가 많거나 커스텀 헤더를 대량으로 쓰는 앱에서 발생한다.
location / {
proxy_pass http://localhost:8080;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
}헤더 크기를 줄이는 게 근본 해결이지만, 당장 급하면 버퍼를 올린다.
원인 4: Unix 소켓 권한 문제
PHP-FPM이나 Gunicorn을 소켓으로 연결할 때 발생한다.
connect() to unix:/var/run/php-fpm.sock failed (13: Permission denied)# 소켓 파일 권한 확인
ls -la /var/run/php-fpm.sock
# 소켓 파일 소유권 변경
chown www-data:www-data /var/run/php-fpm.sock
chmod 660 /var/run/php-fpm.sock; /etc/php-fpm.d/www.conf
listen.owner = www-data
listen.group = www-data
listen.mode = 06603. 빠른 진단 순서
# 1. Nginx 에러 로그 확인 (제일 먼저)
tail -f /var/log/nginx/error.log
# 2. 업스트림 서버 상태 확인
curl -I http://127.0.0.1:8080/
# 3. 포트 리스닝 확인
ss -tlnp | grep 8080
# 4. Nginx 설정 문법 검사
nginx -t
# 5. Nginx 재시작 (설정 변경 후)
systemctl reload nginx에러 로그에 Connection refused, timed out, Permission denied, too big header 중 뭐가 찍혀 있는지 먼저 보는 게 핵심이다.
4. 원인별 체크리스트
| 에러 로그 키워드 | 원인 | 해결 방법 |
|---|---|---|
Connection refused |
업스트림 프로세스 다운 | 앱 재시작 |
timed out |
응답 지연 | proxy_read_timeout 증가 |
too big header |
헤더 버퍼 부족 | proxy_buffer_size 증가 |
Permission denied |
소켓 권한 문제 | 소켓 파일 권한 수정 |
no live upstreams |
업스트림 그룹 전체 다운 | 업스트림 서버 상태 확인 |
5. 실무 팁 — health check 설정
업스트림이 다운됐을 때 Nginx가 알아서 fallback하도록 설정할 수 있다.
upstream backend {
server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
server 127.0.0.1:8081 backup; # 메인이 죽으면 이걸로
}max_fails는 해당 서버를 비활성화하기 전 실패 허용 횟수, fail_timeout은 비활성화 유지 시간이다.
정리
Nginx 502는 반드시 /var/log/nginx/error.log를 먼저 봐야 한다. 에러 메시지가 원인을 정확히 알려준다. Connection refused면 앱 프로세스 확인, timed out이면 타임아웃 설정, too big header면 버퍼 설정 — 이 세 가지가 전체 502의 대부분을 차지한다.
작성일: 2026-06-26
