NginX : corriger “upstream sent too big header”

Lors de la mise en ligne d’un nouveau site, je suis tombé sur une page qui ne fonctionnait pas. Côté navigateur, j’obtenais une erreur 502 Bad Gateway. Côté logs Nginx, le message était beaucoup plus explicite :

upstream sent too big header while reading response header from upstreamCode language: JavaScript (javascript)

Ce message signifie que Nginx a bien reçu une réponse de l’upstream, par exemple PHP-FPM, mais que les en-têtes HTTP envoyés par cet upstream sont trop gros pour les buffers configurés.

En clair : le backend répond, mais Nginx n’arrive pas à lire tous les headers de réponse dans l’espace mémoire prévu. Il coupe donc court et renvoie souvent une erreur 502.

Comprendre l’erreur “upstream sent too big header”

Dans une configuration PHP classique, Nginx reçoit les réponses depuis PHP-FPM via FastCGI. La réponse contient deux parties :

• les en-têtes HTTP, par exemple Set-Cookie, Location, Cache-Control ;
• le corps de la réponse, c’est-à-dire le HTML, JSON, XML, etc.

L’erreur apparaît lorsque la partie “headers” dépasse la taille que Nginx peut lire avec la configuration actuelle.

La documentation Nginx indique que fastcgi_buffer_size définit la taille du buffer utilisé pour lire la première partie de la réponse FastCGI, qui contient généralement une petite réponse avec les headers. Elle indique aussi que fastcgi_buffers définit le nombre et la taille des buffers utilisés pour lire la réponse complète de l’upstream FastCGI.

Dans le cas d’un reverse proxy classique, le même problème peut exister, mais avec les directives proxy_buffer_size et proxy_buffers, pas avec fastcgi_buffer_size.

Causes fréquentes

Sur un site PHP, WordPress ou WooCommerce, cette erreur est souvent déclenchée par des headers trop nombreux ou trop volumineux.

• trop de cookies envoyés avec Set-Cookie ;
• un cookie de session énorme ;
• un plugin qui stocke trop de données dans un cookie ;
• un système SSO ou OAuth qui renvoie de très longs headers ;
• des headers de sécurité très verbeux ;
• une redirection qui ajoute beaucoup d’informations ;
• un framework qui empile les cookies flash/session ;
• une réponse PHP avec beaucoup de headers personnalisés ;
• un reverse proxy devant une application qui renvoie des headers trop gros.

Sur WordPress/WooCommerce, je regarde d’abord les cookies. Un panier, une session, un plugin d’affiliation, un module de tracking ou un système de personnalisation peut vite transformer les headers en millefeuille. Et, comme souvent, le millefeuille finit mal côté infra.

Diagnostic : vérifier l’erreur dans les logs Nginx

Commencez par vérifier les logs Nginx :

sudo tail -f /var/log/nginx/error.logCode language: JavaScript (javascript)

Ou, si votre site possède un fichier de log dédié :

sudo tail -f /var/log/nginx/example.com.error.logCode language: JavaScript (javascript)

Vous devriez voir une ligne de ce type :

2026/05/06 10:42:15 [error] 12345#12345: *678 upstream sent too big header while reading response header from upstream, client: 203.0.113.10, server: example.com, request: "GET /mon-compte/ HTTP/2.0", upstream: "fastcgi://unix:/run/php/php8.3-fpm.sock:", host: "example.com"Code language: PHP (php)

La partie importante est l’upstream :

upstream: "fastcgi://unix:/run/php/php8.3-fpm.sock:"Code language: JavaScript (javascript)

Ici, on sait que le problème concerne PHP-FPM via FastCGI. Il faut donc ajuster les directives fastcgi_*.

Si vous voyez plutôt :

upstream: "http://127.0.0.1:3000/..."Code language: JavaScript (javascript)

alors Nginx agit comme reverse proxy HTTP. Il faut regarder les directives proxy_*.

Solution pour PHP-FPM : augmenter les buffers FastCGI

Si votre serveur utilise Nginx avec PHP-FPM, ajoutez ou ajustez ces directives dans le bloc concerné.

Dans le server block, ou mieux, dans le bloc location ~ \.php$ :

fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;

Exemple dans une configuration PHP-FPM classique :

server {
    server_name example.com;
    root /home/www/example.com/public_html;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;

        fastcgi_buffer_size 32k;
        fastcgi_buffers 16 16k;
    }
}Code language: PHP (php)

Ces valeurs sont souvent suffisantes pour corriger l’erreur sur un site PHP/WordPress. Si les headers sont vraiment énormes, vous pouvez tester :

fastcgi_buffer_size 64k;
fastcgi_buffers 16 32k;

Mais n’augmentez pas à l’aveugle. Des buffers plus gros consomment plus de mémoire par requête active. Sur un serveur très fréquenté, cela peut compter.

Où placer les directives fastcgi_buffers ?

Les directives fastcgi_buffer_size et fastcgi_buffers peuvent être placées dans les contextes http, server ou location, selon la documentation Nginx.

En pratique :

• dans http : réglage global pour tous les sites ;
• dans server : réglage pour un site ;
• dans location : réglage ciblé, souvent le plus propre.

Je préfère commencer par le bloc location PHP du site concerné. Cela évite d’augmenter les buffers pour tous les virtual hosts sans raison.

Tester et recharger Nginx

Après modification, testez toujours la configuration :

sudo nginx -t

Si le test est bon :

sudo systemctl reload nginx

Ou, sur un ancien système :

sudo service nginx reload

Un reload est généralement préférable à un restart, car Nginx recharge la configuration sans couper brutalement les connexions en cours. Le bon vieux service nginx restart fonctionne, mais il est moins élégant.

Solution pour reverse proxy : utiliser proxy_buffer_size

Si Nginx ne parle pas à PHP-FPM mais à un backend HTTP, comme Node.js, Rails, Django, Next.js, un conteneur Docker ou un service interne, les directives à modifier ne sont pas les mêmes.

Dans ce cas, utilisez plutôt :

proxy_buffer_size 32k;
proxy_buffers 16 16k;
proxy_busy_buffers_size 64k;

Exemple :

location / {
    proxy_pass http://127.0.0.1:3000;

    proxy_buffer_size 32k;
    proxy_buffers 16 16k;
    proxy_busy_buffers_size 64k;
}Code language: JavaScript (javascript)

La documentation Nginx sur le module proxy indique que proxy_buffer_size définit la taille du buffer utilisé pour lire la première partie de la réponse du serveur proxifié, partie qui contient généralement les headers.

Donc : fastcgi_* pour PHP-FPM, proxy_* pour un reverse proxy HTTP.

Cas WordPress et WooCommerce

Sur WordPress, cette erreur apparaît souvent sur des pages qui manipulent des sessions, cookies ou redirections :

• page panier ;
• page commande ;
• page “Mon compte” ;
• connexion ou inscription ;
• admin WordPress ;
• plugin membership ;
• plugin d’affiliation ;
• plugin de traduction ;
• plugin de sécurité ;
• plugin qui pose beaucoup de cookies.

WooCommerce peut légitimement envoyer plusieurs cookies, notamment pour le panier et la session. Mais si un plugin ajoute de gros cookies ou multiplie les Set-Cookie, les headers peuvent vite dépasser les buffers Nginx.

Pour inspecter les headers d’une page :

curl -I https://example.com/mon-compte/Code language: JavaScript (javascript)

Pour voir uniquement les cookies envoyés :

curl -sI https://example.com/mon-compte/ | grep -i '^set-cookie'Code language: JavaScript (javascript)

Si la sortie affiche une longue collection de cookies ou des valeurs énormes, la configuration Nginx n’est peut-être qu’une partie du problème. Il faut alors identifier quel plugin ou quelle couche applicative génère ces headers.

Mesurer grossièrement la taille des headers

Pour obtenir une idée de la taille des headers retournés par une URL :

curl -sD - -o /dev/null https://example.com/mon-compte/ | wc -cCode language: JavaScript (javascript)

Cette commande compte la taille des headers de réponse. Ce n’est pas une analyse parfaite, mais cela donne une indication rapide.

Pour afficher les headers complets :

curl -sD - -o /dev/null https://example.com/mon-compte/Code language: JavaScript (javascript)

Sur une page publique classique, des headers énormes sont rarement normaux. Sur une page de login, SSO ou panier, ils peuvent être plus volumineux, mais ils ne doivent pas devenir grotesques.

Attention aux cookies trop gros

Chaque cookie ajouté dans une réponse occupe de la place dans les headers via Set-Cookie. Ensuite, le navigateur renvoie ces cookies dans les requêtes suivantes via le header Cookie.

Donc un cookie trop gros peut provoquer deux familles de problèmes :

• headers de réponse trop gros côté upstream ;
• headers de requête trop gros côté client.

Pour les headers de requête trop gros, le message Nginx peut être différent, par exemple :

client sent too large header while reading client request headersCode language: JavaScript (javascript)

Dans ce cas, il faut plutôt regarder large_client_header_buffers. Mais pour upstream sent too big header, on regarde d’abord fastcgi_buffer_size, fastcgi_buffers, ou les équivalents proxy_*.

Configuration complète pour PHP-FPM

Voici une configuration raisonnable pour un site PHP-FPM qui rencontre cette erreur :

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;

    fastcgi_buffering on;
    fastcgi_buffer_size 32k;
    fastcgi_buffers 16 16k;
    fastcgi_busy_buffers_size 64k;
}Code language: JavaScript (javascript)

Si cela ne suffit pas :

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;

    fastcgi_buffering on;
    fastcgi_buffer_size 64k;
    fastcgi_buffers 16 32k;
    fastcgi_busy_buffers_size 128k;
}Code language: JavaScript (javascript)

Mais là encore, si vous devez monter très haut, cherchez la cause applicative. Un site qui renvoie des headers énormes a souvent un plugin, une session, un cookie ou une redirection qui mérite un petit interrogatoire.

Configuration complète pour reverse proxy

Pour un backend HTTP derrière Nginx :

location / {
    proxy_pass http://127.0.0.1:3000;

    proxy_buffering on;
    proxy_buffer_size 32k;
    proxy_buffers 16 16k;
    proxy_busy_buffers_size 64k;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}Code language: PHP (php)

Pour des headers encore plus gros :

proxy_buffer_size 64k;
proxy_buffers 16 32k;
proxy_busy_buffers_size 128k;

La même logique s’applique : augmentez modérément, testez, puis inspectez la cause.

Ne pas confondre avec client_header_buffer_size

Il existe plusieurs directives Nginx liées aux buffers, et elles ne corrigent pas toutes le même problème.

• fastcgi_buffer_size : headers de réponse venant de PHP-FPM ;
• proxy_buffer_size : headers de réponse venant d’un backend HTTP ;
• large_client_header_buffers : headers de requête envoyés par le client ;
• client_header_buffer_size : buffer initial pour les headers de requête client.

Pour l’erreur upstream sent too big header while reading response header from upstream, le mot clé est upstream. Le problème vient donc de la réponse envoyée par le backend à Nginx, pas directement de la requête envoyée par le navigateur.

Faut-il redémarrer PHP-FPM ?

Si vous modifiez uniquement la configuration Nginx, il suffit de tester puis recharger Nginx :

sudo nginx -t
sudo systemctl reload nginx

Pas besoin de redémarrer PHP-FPM dans ce cas.

En revanche, si vous modifiez la configuration PHP, les pools PHP-FPM ou le code applicatif qui génère les cookies/headers, alors il peut être utile de recharger PHP-FPM :

sudo systemctl reload php8.3-fpmCode language: CSS (css)

ou selon votre version :

sudo systemctl reload php8.4-fpmCode language: CSS (css)

Méthode de résolution étape par étape

Voici la démarche que j’utiliserais aujourd’hui :

1. Repérer l’URL qui déclenche l’erreur 502.
2. Lire le log Nginx pour identifier l’upstream : FastCGI ou proxy HTTP.
3. Augmenter modérément les buffers adaptés : fastcgi_* ou proxy_*.
4. Tester la configuration avec nginx -t.
5. Recharger Nginx avec systemctl reload nginx.
6. Tester l’URL à nouveau.
7. Inspecter les headers avec curl -sD - -o /dev/null.
8. Identifier les cookies ou headers anormalement gros.
9. Corriger le plugin, l’application ou la configuration qui les génère si nécessaire.

Les buffers corrigent le symptôme. L’audit des headers corrige souvent la cause.

Mémo rapide

# Voir l’erreur en direct.
sudo tail -f /var/log/nginx/error.log

# Configuration PHP-FPM / FastCGI.
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;

# Variante plus large.
fastcgi_buffer_size 64k;
fastcgi_buffers 16 32k;
fastcgi_busy_buffers_size 128k;

# Configuration reverse proxy.
proxy_buffer_size 32k;
proxy_buffers 16 16k;
proxy_busy_buffers_size 64k;

# Tester Nginx.
sudo nginx -t

# Recharger Nginx sans coupure brutale.
sudo systemctl reload nginx

# Voir les headers d’une URL.
curl -sD - -o /dev/null https://example.com/

# Voir uniquement les Set-Cookie.
curl -sI https://example.com/ | grep -i '^set-cookie'

# Compter grossièrement la taille des headers.
curl -sD - -o /dev/null https://example.com/ | wc -cCode language: PHP (php)

Conclusion

L’erreur Nginx upstream sent too big header while reading response header from upstream indique que l’upstream, souvent PHP-FPM, renvoie des headers trop gros pour les buffers configurés.

Pour un site PHP-FPM, la correction classique consiste à ajouter :

fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;

Pour un reverse proxy HTTP, utilisez plutôt :

proxy_buffer_size 32k;
proxy_buffers 16 16k;

Ensuite, testez la configuration avec nginx -t, puis rechargez Nginx avec systemctl reload nginx.

Enfin, si l’erreur revient, ne vous contentez pas d’augmenter les buffers encore et encore. Inspectez les headers, notamment les Set-Cookie. Un backend qui envoie des headers énormes cache souvent un cookie dodu, un plugin bavard ou une session qui a pris ses aises. Nginx râle, mais parfois il a raison.

Report a typo