Errores de NGINX y cómo solucionarlos

Al gestionar un sitio web con NGINX, pueden aparecer errores que impiden su correcto funcionamiento. Esta guía cubre los más habituales — 502 Bad Gateway, 504 Gateway Time-out y 413 Request Entity Too Large — y explica paso a paso cómo resolverlos en un VPS o en servidores dedicados.

502 Bad Gateway

Qué significa: NGINX no puede obtener respuesta del backend (PHP-FPM, Apache, Node.js, uWSGI, etc.).

Causas más comunes:

• El servicio backend está detenido o ha fallado
• Ruta del socket o puerto incorrectos en la configuración
• Permisos incorrectos en el socket
• Memoria o procesos worker insuficientes en PHP-FPM

Cómo resolverlo:

1. Comprueba el estado de PHP-FPM (o de tu backend):

sudo systemctl status php-fpm
# o para una versión específica
sudo systemctl status php8.1-fpm

2. Reinicia el servicio:

sudo systemctl restart php-fpm
# o php8.1-fpm

3. Verifica la ruta del socket en las configuraciones de NGINX y PHP-FPM:

   • NGINX: fastcgi_pass unix:/run/php/php8.1-fpm.sock;
   • PHP-FPM (/etc/php/8.1/fpm/pool.d/www.conf): listen = /run/php/php8.1-fpm.sock

4. Corrige los permisos si es necesario:

sudo chown www-data:www-data /run/php/php8.1-fpm.sock
sudo chmod 660 /run/php/php8.1-fpm.sock

5. Prueba y recarga NGINX:

sudo nginx -t && sudo systemctl reload nginx

504 Gateway Time-out

Qué significa: NGINX esperó demasiado tiempo la respuesta del backend y agotó el tiempo de espera.
Causas más comunes:

• Ejecución lenta de un script PHP
• Consultas lentas a la base de datos
• Alta carga del servidor

Cómo resolverlo:

1. Aumenta los timeouts en la configuración del sitio (en el bloque server o location):

proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
fastcgi_read_timeout 300s;  # para PHP

2. Optimiza PHP-FPM (en /etc/php/8.1/fpm/pool.d/www.conf):

pm.max_children = 50          # aumenta según sea necesario
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
request_terminate_timeout = 300

3. Reinicia los servicios:

sudo systemctl restart php-fpm
sudo systemctl reload nginx

4. Si el problema está en un script concreto — optimiza las consultas a la BD o añade caché para las páginas pesadas.

413 Request Entity Too Large

Qué significa: El cliente está intentando subir un archivo que supera el límite permitido por NGINX (1 MB por defecto).
Causas habituales: subida de archivos de gran tamaño (fotos, vídeos, copias de seguridad, archivos comprimidos).

Cómo resolverlo:

1. Aumenta el límite en la configuración del sitio (o en /etc/nginx/nginx.conf, en el bloque http):

client_max_body_size 64M;  # o 128M, 512M, 1G, etc.

2. Recarga NGINX:

sudo nginx -t && sudo systemctl reload nginx

3. Aumenta también los límites de PHP en el php.ini (/etc/php/8.1/fpm/php.ini):

upload_max_filesize = 64M
post_max_size = 64M

Reinicia PHP-FPM:

sudo systemctl restart php-fpm

Cómo recargar NGINX correctamente

• Comprueba siempre la configuración primero:

sudo nginx -t

• Recarga sin interrupciones (graceful reload):

sudo systemctl reload nginx

o bien

sudo nginx -s reload

• Reinicio completo (solo si el reload no resuelve el problema):

sudo systemctl restart nginx

Notas útiles

• Haz siempre una copia de seguridad de las configuraciones antes de realizar cambios: sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
• Tras cualquier cambio, revisa los logs: /var/log/nginx/error.log y /var/log/nginx/access.log