Por qué falla un despliegue en realidad, razón por razón
“El despliegue falló” no es un solo problema —son por lo menos una docena distintos que resultan viéndose igual para alguien que le echa un vistazo rápido a un panel. Saber cuál pasó realmente es la mayor parte del arreglo, por eso la página de un despliegue fallido empieza con por qué falló: la causa, el arreglo y la línea del log que lo demuestra.
Las dos que se ven idénticas pero no lo son
La confusión más común con diferencia: “el build se quedó sin tiempo” (se detuvo en un límite de 60 minutos; el siguiente intento reutiliza lo que ya se construyó) versus “el build se quedó sin memoria” (un paso del build fue eliminado de plano por exceder lo que tiene el servidor de build). Las dos se ven como “el build simplemente no terminó” con solo mirar un estado rojo —el arreglo de una es paciencia y reutilizar el trabajo parcial, el arreglo de la otra es un servidor de build más grande o desplegar una imagen ya construida en vez de construir en la plataforma.
La app corre, pero de alguna forma no
Esta merece su propio apartado porque casi nunca es obvio desde el código propio de la app: el contenedor está corriendo, pero nada responde por HTTP. No se cayó —está corriendo, sano según cada métrica excepto la que importa. La causa real casi siempre es un arreglo de una línea: la app tiene que escuchar en 0.0.0.0, no en 127.0.0.1, y en el puerto de $PORT, no en uno fijo. Una app perfectamente correcta, corriendo perfectamente bien, que solo se habla a sí misma.
Un pariente cercano: el comando corrió en la carpeta equivocada —la imagen no contiene la app donde el comando de arranque la espera, usualmente porque se usó para un build real un Dockerfile escrito para desarrollo local (que espera un bind mount). Cambiar a Railpack en vez del Dockerfile propio del repo es el arreglo cuando esa es la situación real.
Las fallas con forma de base de datos, de tres maneras distintas
- La base de datos no era alcanzable —más confuso cuando pasa durante el build, porque una app que se conecta a su base de datos mientras compila assets o corre una comprobación en tiempo de build está intentando alcanzar infraestructura a la que ese paso del build nunca iba a tener acceso.
- Al usuario de la base de datos le falta un permiso —una migración necesita algo que el usuario de base de datos de la app todavía no tiene. El arreglo es casi sospechosamente simple: redespliega una vez, porque los permisos se refrescan en cada despliegue.
- El paso de release falló —casi siempre migraciones, que corren una vez antes de que la versión nueva reciba tráfico. La primera línea del error real se muestra directo en la página del despliegue, no enterrada en un volcado completo del log.
Las dos que son en realidad el mismo problema con distinta ropa
Una variable requerida no está definida (la app se detiene al arrancar porque algo que necesita está vacío) y la app necesita credenciales para un servicio externo (una API de terceros, almacenamiento en la nube, email, pagos —sin clave configurada) son la misma causa raíz —una variable de entorno faltante— con distinta especificidad. Una es “falta algo”, la otra nombra qué categoría de algo.
La imagen no se pudo descargar (no existe, tag equivocado, o privada sin credenciales) y el nombre de la imagen es inválido (caracteres que Docker no acepta) son el par equivalente para despliegues basados en imagen en vez de basados en build.
Por qué nombrar la causa exacta importa más de lo que suena
Cada una de estas produce el mismo síntoma visible para alguien que le echa un vistazo a un panel: un estado rojo y un despliegue fallido. El arreglo real solo se vuelve obvio una vez que se nombra la causa específica —“se quedó sin tiempo” y “se quedó sin memoria” necesitan respuestas opuestas; un pipeline de despliegue confiable tiene menos que ver con nunca fallar y más con que una falla te diga de inmediato y con precisión qué hacer después.
Referencia completa, cada causa: Solución de problemas de despliegues fallidos.