Nginx 502 "too big header" 오류 해결

error.log 에 아래 줄이 찍히고 클라이언트에는 502 가 나갑니다. 줄 앞의 시각·PID 와 중간의 client:·server: 는 … 로 줄였습니다. 이 문구가 아닌 502 는 다른 글에서 문구별로 가릅니다.

… [error] … *1 upstream sent too big header while reading response header from upstream, … request: "HEAD / HTTP/1.1", upstream: "http://127.0.0.1:18602/", …

[1] 원인은 백엔드가 보낸 응답 헤더 입니다. 상태 줄과 헤더는 proxy_buffer_size 크기의 버퍼 하나에 모두 들어와야 하고, 넘으면 응답이 잘못된 것으로 처리됩니다(공식 문서). 기본값은 메모리 페이지 하나(4k 또는 8k)입니다. 가장 흔한 범인은 세션·추적용 Set-Cookie 가 커진 경우입니다.

[2] 백엔드에 직접 요청해 헤더 크기를 잽니다. Nginx 를 거치지 않으므로 같은 주소·포트를 쓰는 백엔드로 보냅니다.

$ curl -sI http://127.0.0.1:18602/ | wc -c8333

시험 백엔드는 8KB 짜리 Set-Cookie 하나를 내며, 헤더 전체가 8,333바이트였습니다. 이 값보다 큰 버퍼가 필요합니다.

[3] proxy_buffer_size 를 헤더 크기보다 크게 잡습니다. 문제 구간의 location(또는 server·http)에 넣습니다. 아래는 4k 기본값에서 502 가 나던 요청이 12k 로 200 이 된 결과입니다.

location / {    proxy_pass http://127.0.0.1:18602;  proxy_buffer_size 12k;}

# nginx -t && systemctl reload nginx$ curl -sI http://127.0.0.1:18601/ | head -1HTTP/1.1 200 OK

[4] 더 크게 잡다가 nginx -t 가 거부하는 경우가 있습니다. proxy_buffer_size 16k; 만 쓰면 기본 proxy_buffers(8개 × 4k)와 맞지 않아 아래 오류가 납니다.

# nginx -tnginx: [emerg] "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer in /etc/nginx/conf.d/app.conf:4

proxy_busy_buffers_size 를 직접 정해 줍니다. 시험에서 통과한 조합은 이렇습니다.

location / {    proxy_pass http://127.0.0.1:18602;  proxy_buffer_size 16k;  proxy_busy_buffers_size 24k;}

[5] 두 값 사이의 제약은 오류 문구가 둘로 나뉩니다. 아래 표는 시험에서 nginx -t 가 낸 결과입니다(proxy_buffers 는 설정하지 않으면 8 × 4k).

proxy_busy_buffers_size 는 proxy_buffer_size 와 proxy_buffers 의 버퍼 하나 중 큰 쪽 이상이어야 하고, proxy_buffers 전체 크기에서 버퍼 하나를 뺀 값을 넘으면 안 됩니다. 버퍼 수가 적으면 이 범위가 좁아지므로, 거부되면 proxy_buffers 의 개수를 늘립니다.

[6] fastcgi_pass 뒤의 PHP-FPM 이 응답 헤더 때문에 막히면 fastcgi_buffer_size 를 올립니다. 공식 문서의 설명이 proxy_buffer_size 와 같은 구조입니다. 설정 검사에서 거부되면 4단계처럼 fastcgi_busy_buffers_size 를 함께 정합니다.

location ~ \.php$ {    fastcgi_pass unix:/run/php/php-fpm.sock;  fastcgi_buffer_size 16k;}

[7] large_client_header_buffers 는 클라이언트가 보낸 요청 헤더용입니다. 이 오류에는 듣지 않습니다. 시험에서 large_client_header_buffers 4 32k; 를 http 에 넣고 같은 요청을 보냈지만 502 가 그대로였습니다. 이 지시어가 막는 것은 414·400 입니다.