Cómo Solucionar el Error 503 Service Unavailable en Magento 2 Paso a Paso

¿Qué es el Error 503 Service Unavailable en Magento 2?

El error 503 Service Unavailable en Magento 2 indica que el servidor web no está disponible temporalmente para atender las solicitudes de los usuarios. En el ecosistema de Magento, este fallo suele estar estrechamente relacionado con el archivo de mantenimiento del sistema, problemas de sobrecarga en el servidor PHP-FPM o fallos tras ejecutar comandos de despliegue.

Principales Causas del Error 503 en Magento

• El archivo maintenance.flag ha quedado atascado en la raíz del proyecto.
• Agotamiento de los recursos del servidor (memoria RAM o procesos de PHP-FPM).
• Errores críticos durante la compilación o actualización de módulos.
• Problemas de configuración en el servidor web (Nginx o Apache).

Método 1: Eliminar el archivo maintenance.flag

Cuando ejecutas comandos de actualización en Magento 2, el sistema crea automáticamente un archivo para bloquear el acceso público. Si el proceso se interrumpe, este archivo no se borra y la tienda queda inaccesible mostrando el error 503.

1. Conéctate a tu servidor mediante SSH utilizando tus credenciales de acceso.
2. Navega hasta el directorio raíz de tu instalación de Magento: cd /var/www/html/tu-tienda-magento
3. Busca el archivo de mantenimiento con el siguiente comando: ls -la | grep maintenance.flag
4. Si el archivo existe, elimínalo ejecutando: rm var/maintenance.flag o rm generated/maintenance.flag según corresponda.
5. Recarga tu sitio web en el navegador para comprobar que el error ha desaparecido.

Método 2: Limpiar y regenerar la caché y el código generado

Un estado inconsistente en la caché o en las clases generadas de Magento puede colapsar el sistema y devolver un error 503.

1. Accede a tu servidor por SSH con permisos de usuario de Magento (por ejemplo, www-data).
2. Ejecuta el comando para limpiar la caché: php bin/magento cache:clean
3. Limpiar el directorio de código generado: rm -rf generated/code/* generated/metadata/*
4. Vuelve a compilar la aplicación si es necesario: php bin/magento setup:di:compile
5. Habilita nuevamente la caché: php bin/magento cache:enable

Método 3: Verificar los límites de PHP-FPM y reiniciar servicios

Si el servidor se queda sin recursos debido a un límite bajo en PHP-FPM, las peticiones fallarán generando el código 503.

1. Abre el archivo de configuración de PHP-FPM en tu servidor (la ruta puede variar según tu versión de PHP): sudo nano /etc/php/8.1/fpm/pool.d/www.conf
2. Asegúrate de que los parámetros pm.max_children, pm.start_servers y pm.min_spare_servers estén ajustados correctamente al tamaño de tu servidor VPS o dedicado.
3. Reinicia el servicio PHP-FPM para aplicar los cambios: sudo systemctl restart php8.1-fpm
4. Reinicia también tu servidor web (Nginx o Apache): sudo systemctl restart nginx