Eroarea 502 Bad Gateway: cauze și remediere

Ce înseamnă eroarea

Un 502 este răspunsul unui server care funcționează. Serverul web din față (nginx, Apache, un load balancer sau un CDN precum Cloudflare) a primit cererea, a trimis-o mai departe către aplicația din spatele lui (PHP-FPM, un proces Node.js sau Python, un server backend) și nu a primit înapoi un răspuns utilizabil: conexiunea a fost refuzată, întreruptă sau a returnat date fără sens. „Gateway” este serverul din față; „bad” este ce a venit din spate.

Deci un 502 îți spune două lucruri deodată: partea din față funcționează, iar cea din spate este căzută sau defectă. Asta restrânge considerabil căutarea.

Cauze frecvente

1. Procesul aplicației nu rulează. PHP-FPM s-a prăbușit sau a fost oprit, procesul Node.js a murit, containerul s-a oprit. Partea din față nu se poate conecta deloc.
2. Aplicația este suprasolicitată. Toți workerii PHP-FPM sunt ocupați, coada este plină, conexiunile noi sunt refuzate. Adesea după un vârf de trafic sau o interogare lentă a bazei de date care blochează fiecare worker.
3. Un socket sau un port greșit în configurație. După o actualizare sau o schimbare a versiunii PHP, nginx încă indică php8.2-fpm.sock, în timp ce noul pool ascultă pe php8.4-fpm.sock.
4. Timeout-uri setate prea strâns. Backendul răspunde, dar mai târziu decât este dispusă partea din față să aștepte. Unele configurații raportează aceasta ca 502, altele ca 504 Gateway Timeout.
5. Backendul trimite un antet prea mare sau un răspuns nevalid. Tipic pentru framework-uri care pun mult în cookie-uri; nginx înregistrează atunci în log „upstream sent too big header”.
6. CDN-ul nu ajunge la serverul tău. Cu Cloudflare în față, o pagină 502 cu logoul Cloudflare înseamnă că Cloudflare nu a primit nimic de la serverul tău de origine: firewall, IP greșit după o mutare sau serverul pur și simplu e căzut.

Dacă ești vizitator

Nu poți repara un 502 pe site-ul altcuiva. Reîncarcă o dată după un minut; dacă persistă, proprietarul site-ului trebuie să acționeze. Pentru propriul site, continuă să citești.

Dacă e site-ul tău: verifică mai întâi

E căzut pentru toată lumea? Rulează website down checker. Arată codul de status din exterior și dacă a răspuns un CDN sau serverul de origine.

Hosting partajat sau site builder? Un 502 acolo este aproape întotdeauna problema furnizorului (un pool PHP suprasolicitat pe un nod partajat). Sari la mesajul pentru furnizorul tău de mai jos.

Propriul server: autentifică-te prin SSH și întreabă serverul web ce a mers prost.

# nginx: ultimele erori, cele mai noi jos
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Linii tipice și ce înseamnă:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM nu rulează sau calea socketului este greșită.
• connect() failed (111: Connection refused) while connecting to upstream: portul backendului nu ascultă.
• upstream prematurely closed connection: procesul backend s-a prăbușit în timp ce răspundea, adesea o eroare fatală PHP sau lipsă de memorie.
• upstream sent too big header: mărește buffer-ele (vezi mai jos).
• (11: Resource temporarily unavailable): toți workerii PHP-FPM sunt ocupați.

Remedieri pe propriul server

1. Pornește serviciul oprit

# află versiunea PHP-FPM pe care o folosești
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# aplicații Node.js sau Python gestionate de systemd
sudo systemctl restart myapp

Dacă serviciul refuză să pornească, motivul se află în journalctl -u php8.3-fpm -n 50. Cel mai frecvent este un disc plin (df -h), al doilea o eroare de sintaxă într-o configurație de pool (sudo php-fpm8.3 -t).

2. Repară socketul sau portul

Compară la ce se conectează nginx cu ce ascultă PHP-FPM:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Cele două trebuie să coincidă. După o modificare, testează întotdeauna configurația înainte de reîncărcare:

sudo nginx -t && sudo systemctl reload nginx

Cu Apache și PHP-FPM prin mod_proxy_fcgi, aceeași verificare se aplică liniei SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; testează cu sudo apachectl configtest.

3. Dă-i loc lui PHP-FPM

Dacă logul de erori spune că workerii sunt ocupați sau server reached pm.max_children, mărește limita în fișierul pool-ului (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Fiecare worker are nevoie de memorie (adesea 30 până la 80 MB pentru WordPress); verifică free -m înainte să mărești numărul și caută interogarea lentă sau pluginul care ține workerii ocupați de la bun început.

4. Mărește buffer-ele pentru antete mari

În blocul server nginx:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. Particularități WordPress

Un 502 imediat după o actualizare de plugin sau temă înseamnă de obicei că PHP rămâne fără memorie sau dă o eroare fatală la fiecare cerere. Redenumește folderul pluginului prin SFTP sau SSH ca să-l oprești (wp-content/plugins/plugin-name în plugin-name.off), apoi reîncarcă site-ul. Mărește memory_limit în pool sau în php.ini dacă journalctl arată „Allowed memory size exhausted”. Dacă folosești WP-CLI: wp plugin deactivate plugin-name.

6. În spatele Cloudflare

Verifică dacă originea răspunde direct: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Dacă funcționează, firewall-ul de pe server ar putea bloca intervalele de adrese ale Cloudflare sau înregistrarea DNS din Cloudflare indică un IP vechi.

Când e problema furnizorului tău de hosting

Pe hosting partajat nu poți reporni PHP-FPM. Trimite-i furnizorului tău acest mesaj, cu ora și eroarea exactă:

Bună ziua, site-ul meu example.com returnează „502 Bad Gateway” începând cu aproximativ 14:30 UTC. O verificare din exterior o confirmă; nu am schimbat nimic din partea mea. Ați putea verifica procesele PHP și serverul web de pe contul meu de hosting și să-mi spuneți când revine?

Prevenirea următorului

Un 502 este aproape întotdeauna un backend oprit sau suprasolicitat, iar ambele sunt vizibile înainte ca vizitatorii să observe: un serviciu PHP-FPM oprit, memorie care se epuizează, un disc care se umple. Monitorizarea serverului cu agentul raportează exact acestea din interiorul serverului, iar verificările de site din exterior prind 502 în momentul în care apare. Pe propriul server, un Quick Fix poate reporni serviciul oprit după ce testul configurației trece; dacă cauza este mai adâncă, preia un Deep Fix, non-stop.