# Cómo depurar un deploy fallido: encontrá la etapa y después corregí

Un deploy fallido se corta en una etapa. Leé ese log y cambiá lo mínimo. Volver a desplegar sin saber dónde falló puede esconder la evidencia.

Canonical URL: https://unbroker.cloud/es/blog/debug-failed-deployment
Published: 2026-11-04
Reviewed: 2026-11-04
Author: Timoteo Borgobello

## La respuesta corta

Un deploy fallido se corta en una etapa. Nombrá esa etapa con la evidencia que dejó, y recién ahí cambiá lo mínimo que la explica. Volver a desplegar antes de saber la etapa puede esconder esa evidencia.

Unbroker registra el commit, la salida del build, el rollout y el estado final de salud. El corte más fino, desde un error de clone hasta un comando post-deploy, es cómo se lee una falla concreta. El recorrido para un agente está en [Diagnose a failed deployment](https://docs.unbroker.cloud/guides/debug-failed-deployment).

## Las etapas de un deployment

Un deployment convierte una revisión de código en un servicio en ejecución. El [overview de deployments](https://docs.unbroker.cloud/deployments/overview) lista cuatro etapas:

1. **Queued.** El deployment fue aceptado y asignado al sistema de build.
2. **Building.** Se instalan las dependencias y se crea el artefacto o la imagen de producción.
3. **Deploying.** La revisión nueva se despliega y se le hace el health check.
4. **Live.** El tráfico puede llegar a la revisión sana.

Un health check fallido impide que una revisión que no está sana se trate como live. Revisá los logs de build y de runtime antes de reintentar. El overview no describe un reintento automático, y no describe un rollback automático.

Si el push nunca encoló un deployment, la falla es anterior a estas cuatro etapas. Qué rama despliega, qué rutas cuentan y cuándo Unbroker espera los checks está en [Desplegar con git push](https://unbroker.cloud/es/blog/deploy-on-git-push). La espera en sí es [Wait for CI](https://unbroker.cloud/changelog/2026-10-05-wait-for-ci).

Para seguir un deployment hasta que termina:

```bash
ubctl apps deploy <serviceId> --wait
```

`--wait` consulta hasta que el deployment llega a un estado terminal y sale con un código distinto de cero si falla. Ese comportamiento está en la [CLI de deployments](https://docs.unbroker.cloud/cli/deployments).

## Log del deployment y logs de runtime

La salida del deployment describe el build y el intento de release. Los logs del servicio describen el proceso en ejecución. Confirmá los timestamps y la revisión de origen para no estar leyendo un deployment viejo u otro entorno.

```bash
ubctl whoami
ubctl apps services get <serviceId>
ubctl apps deployments <serviceId>
ubctl apps deployment <deploymentId> --log
ubctl apps services logs <serviceId> --since 30m
```

Reemplazá los placeholders con los ids de esa falla. `ubctl whoami` confirma la organización activa antes de leer cualquier otra cosa. Esos comandos son el paso de juntar evidencia en la guía.

[Logs, metrics, and monitoring](https://docs.unbroker.cloud/apps/monitoring) separa las mismas señales. Cómo esas señales se vuelven alertas, y qué no alcanzan a ver, está en [Logs, métricas y alertas](https://unbroker.cloud/es/blog/logs-metrics-alerts). El log de build dice por qué una revisión se construyó o no. El log de runtime es lo que escribe la aplicación en ejecución. El historial de deployments dice qué cambió y qué revisión está live. Las líneas de runtime se guardan 7 días. La salida del build queda en cada deployment. La salida de build de más de 90 días se borra, salvo la del deployment que el servicio está corriendo ahora. Un deploy posterior es otro registro. Leer el commit equivocado, la hora equivocada u otro entorno es la forma en que se esconde la evidencia.

## Clasificá la falla

| Etapa | Evidencia útil | Siguiente chequeo |
| --- | --- | --- |
| Código fuente o instalación de dependencias | Errores de clone y de instalación | Acceso al repositorio, el lockfile y el origen de las dependencias |
| Compilación | El primer error de compilador o de build que se puede actuar | Comando de build, versión del runtime y salida esperada |
| Arranque | La salida del proceso y la primera excepción de runtime | Comando de start, archivos que faltan o variables requeridas |
| Health check o routing | Dirección de escucha y respuesta de la sonda | `PORT`, `0.0.0.0`, el path del endpoint y la duración del arranque |
| Request de la app | Estado HTTP y el error de ese request | Conectividad a la base, migraciones o lógica de la aplicación |
| Comando post-deploy | `postDeployStatus: failed` con el deployment en `live`, más la salida del comando en el log del deployment. Si el control plane se detiene durante el comando, se registra el mismo estado y el comando no se vuelve a ejecutar | El comando, su timeout y las variables del servicio. El release no se revierte |

La tabla es la de la guía. La memoria agotada no es una fila propia. Tratala como evidencia, y fijate si pasó durante el build o durante la ejecución antes de cambiar un ajuste. Son etapas distintas.

## Fallos de build: dependencias y compilación

Una falla de build se queda en Building. El deployment no llega al health check.

Empezá por el acceso al repositorio, el lockfile y de dónde salen las dependencias. La [guía de Node.js](https://docs.unbroker.cloud/guides/deploy-nodejs) dice que commitees el lockfile que produjo tu package manager. Si el build instala paquetes privados, la [guía de Docker](https://docs.unbroker.cloud/guides/deploy-docker) dice que pases el token como secreto de BuildKit, con el nombre que espera la herramienta. Los tokens no se pasan como argumentos de build.

Usá el primer error de compilador o de build que se puede actuar. Después revisá el comando de build, la versión del runtime y si existe la salida esperada. En un log de build muy grande, Unbroker conserva el principio y la salida más reciente, así que la última línea no es el único lugar donde mirar. Esa regla de retención está en la documentación de monitoring.

Con Bun, un repositorio que tiene `bun.lock` o `bun.lockb` en la raíz se instala y se construye con Bun. Si no fijás una versión, los builds usan Bun 1.4.2. Un pin exacto se lee de `"packageManager"` en `package.json`, después de un archivo `.bun-version`, y después de `"engines"`. El `bun@1.3.3` de la documentación es un ejemplo de pin exacto, no el default. Solo se respetan versiones exactas desde 1.2.0. Un rango como `>=1.1` usa el default. El log de build dice qué versión se usó y por qué. Un server cuyo comando de start usa Bun corre en esa misma versión. La fuente es [service types](https://docs.unbroker.cloud/apps/services).

Un build con Dockerfile usa la imagen base de ese archivo. El ejemplo de la guía de Docker es `FROM node:22-slim`. Ese tag es el ejemplo, no un default de la plataforma. La [guía de Fastify](https://docs.unbroker.cloud/guides/deploy-fastify) dice que verifiques que la versión de Node.js elegida alcance lo que pide la versión de Fastify instalada.

## Fallos de arranque: el proceso se cierra

La imagen existe, y el proceso se cierra antes de poder atender. La evidencia es esa salida y la primera excepción de runtime. Revisá el comando de start, los archivos que faltan y las variables que el proceso necesita.

La guía de Node.js nombra tres causas típicas: falta el script de start, no se generó un archivo compilado, y falta una variable de entorno que hace falta durante el arranque. Una app en TypeScript necesita un build que produzca JavaScript y un comando de start que apunte a esa salida. La guía de Fastify dice que mires el primer error de arranque antes de reintentar. La [guía de FastAPI](https://docs.unbroker.cloud/guides/deploy-fastapi) dice que un error de import suele significar que el path del módulo no coincide con el repositorio, o que faltó una dependencia, y que leas los logs de runtime antes de subir recursos.

Si falta una variable, cargala en Cloud. No pongas el valor en un prompt ni en un log copiado. Ese paso es [Environment variables](https://docs.unbroker.cloud/guides/environment-variables).

## Health check y routing

Deploying incluye el health check. Un chequeo fallido impide que esa revisión se trate como live.

El proceso tiene que escuchar en `0.0.0.0` y en el `PORT` que recibe, no en un localhost fijo. La guía de Node.js dice que un build exitoso solo no prueba que el server sea alcanzable. `EXPOSE` en un Dockerfile no levanta un server ni publica un puerto. Lo hace el listener. Escuchar solo en localhost es una diferencia común entre un proceso que anda en tu máquina y un contenedor al que nadie llega. Esa frase está en la guía de Fastify.

Los otros chequeos son el path del endpoint y la duración del arranque. Si la sonda llama un path que la app no sirve, el chequeo falla. En Pro, la guía de Fastify dice que apuntes el health check del servicio a `/health` cuando esa es la ruta. [Plans](https://docs.unbroker.cloud/billing/plans) lista los health checks avanzados como no disponibles en Free y disponibles en Pro. La documentación no publica una cantidad de segundos para el arranque. Si el proceso todavía está levantando cuando corre la sonda, leé el log de runtime y buscá la primera excepción antes de cambiar el path.

Un proceso sin listener no debería forzarse por un health check HTTP. Usá un worker. La [guía del worker](https://docs.unbroker.cloud/guides/background-worker) dice que los workers con Dockerfile corren sin URL pública y sin sonda de readiness HTTP. Cómo un archivo Compose se reparte en esos servicios está en [Docker Compose en producción](https://unbroker.cloud/es/blog/docker-compose-to-production).

## Quedó live, pero un endpoint falla

Live quiere decir que el health check pasó y que el tráfico puede llegar a esa revisión. No quiere decir que cada ruta funcione. Cuando el deployment está live, pedí el endpoint que te importa y leé la respuesta.

Si el hostname default de Unbroker responde y solo falla el dominio personalizado, el deployment ya está live. DNS, la verificación del hostname y el certificado son los tres estados en [Dominio personalizado y HTTPS](https://unbroker.cloud/es/blog/custom-domain-https). Redesplegar el mismo commit no arregla eso.

Una respuesta sana no prueba que funcione una feature que depende del schema. La guía de Fastify dice que la ruta de health del ejemplo no prueba que haya una base. La [guía de Next.js](https://docs.unbroker.cloud/guides/deploy-nextjs) dice que una home que renderiza no ejercita toda la aplicación. Los chequeos que siguen son la conectividad a la base, las migraciones y la lógica de la aplicación.

Las migraciones son un paso de release aparte. Dónde corre ese comando, y por qué un rollback deja el schema en su lugar, está en [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy).

## Memoria agotada: ¿en el build o en ejecución?

Tratá la memoria agotada como evidencia. Fijate si pasó durante el build o con el proceso ya corriendo antes de cambiar un ajuste. La guía separa esas etapas.

Si el build se queda sin memoria, la guía de Next.js dice que mires dónde: instalación de dependencias, compilación o generación de páginas. Sacá trabajo que el build no necesita, o ajustá la capacidad que aplica a esa etapa. Más réplicas de runtime no arreglan un build que se quedó sin memoria. La guía de FastAPI dice que leas los logs de runtime antes de subir recursos: esa es la otra etapa, el proceso ya está corriendo.

En Pro, la pestaña Resources muestra CPU y memoria contra los límites con los que corre el servicio. Las métricas de recursos son una función de Pro. Los límites de CPU y memoria son fijos en Free y configurables en Pro. Esas filas están en [Plans](https://docs.unbroker.cloud/billing/plans). El comando que cambia el límite en ejecución está en [scaling](https://docs.unbroker.cloud/cli/scaling). Usalo después de que el log diga que el proceso en ejecución es la etapa que se quedó sin memoria.

## Falló el comando post-deploy

Un servicio de repositorio puede correr un comando después de que el deployment ya está live. Corre en una copia de un solo uso de la imagen nueva, con las variables de entorno de ese servicio, como máximo 10 minutos. La salida se agrega al log del deployment.

Si el comando falla, el deployment queda `live` y no se revierte nada. `postDeployStatus` es `running`, `succeeded` o `failed`. El comando no corre cuando el deploy en sí falla. Si el control plane se detiene mientras el comando está corriendo, la misma falla se registra cuando vence el lease del deploy, y el comando no se vuelve a iniciar.

El comando no monta un volumen persistente. Los servicios on-demand no necesitan estar despiertos para eso, y la protección de acceso privado no aplica a esa copia de un solo uso. Poné los secretos en variables de entorno, no en el string del comando. El comando en sí no se imprime en el log, y los valores largos de entorno se enmascaran.

Los comandos post-deploy requieren un plan pago y no están disponibles para servicios de imagen. `ubctl` e infrastructure as code todavía no aceptan el campo. `@unbroker/iac` v0.2.0 solo tiene `preDeploy`. Definí `postDeployCommand` en los ajustes del servicio, o con `PATCH /apps/services/:id`. Cambiar el comando marca el servicio para redesplegar. Las fuentes son la [CLI de deployments](https://docs.unbroker.cloud/cli/deployments) y la [nota del 26 de octubre](https://unbroker.cloud/changelog/2026-10-26-post-deploy-command).

## Recuperar: un deploy nuevo, o un rollback

Corregí la causa que encontraste, y desplegá de nuevo esperando el resultado:

```bash
ubctl apps deploy <serviceId> --wait
```

Pedí el endpoint afectado. Confirmá que la falla original ya no está. Una respuesta sana sigue sin probar una feature que depende del schema. Incluí un chequeo de esa feature.

Un rollback es la otra recuperación, y es un comando que corrés vos. La documentación no describe que Unbroker lo inicie solo.

```bash
ubctl apps rollback svc_123 dep_previous
```

En la documentación, `svc_123` y `dep_previous` representan el servicio y el deployment que estás promoviendo. Un rollback promueve un deployment conocido. No reconstruye el commit de origen. No restaura una base, un volumen ni un efecto externo. Volver a una imagen anterior tampoco deshace cambios de configuración ni escrituras en la base. Revisá el schema y los datos antes de elegirlo. Esas frases están en la [CLI de deployments](https://docs.unbroker.cloud/cli/deployments), la [guía de diagnóstico](https://docs.unbroker.cloud/guides/debug-failed-deployment) e [infrastructure as code](https://docs.unbroker.cloud/cli/infrastructure-as-code). Qué significa eso para una migración está en [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy). Un archivo que desapareció es otra falla, distinta de un crash. Si solo estaba en el filesystem del contenedor, [Volúmenes persistentes](https://unbroker.cloud/es/blog/persistent-storage-volumes) explica qué sobrevive a un redespliegue y qué borran Reset, Detach y borrar el servicio.

En Free, los deploy requests son 3 por día UTC. Los que no se usan no se acumulan. Pro no tiene un tope de requests por plan. Esa fila está en [Plans](https://docs.unbroker.cloud/billing/plans). Es un motivo para clasificar la etapa primero. Los otros límites de ese plan, incluido el sueño y el tope de servicios, están en [límites de deploy y de runtime del plan Free](https://unbroker.cloud/es/blog/free-backend-hosting).

## Hacerlo en Unbroker

La vista del proyecto muestra logs en vivo, salud e historial de deployments de cada servicio. Las métricas están en Pro. Los logs de runtime están en Free y en Pro. Los comandos de arriba necesitan un token de API, y los tokens de API requieren Pro. Las apps públicas de Node.js que califican se pueden crear en Cloud en Free. La guía de Node.js marca ese corte.

Un agente de código puede leer la misma evidencia con el skill `ubctl-ops`. Mientras diagnostica, no tiene que cambiar recursos. El prompt de la guía es:

```text
Use ubctl-ops to diagnose deployment [deployment ID] for service
[service ID]. Confirm the active organization, inspect deployment
output and recent runtime logs, and identify the first actionable
failure. Do not change resources yet. Report the evidence, likely
cause and smallest proposed fix. Redact credentials and user data.
```

Cuando el diagnóstico se sostiene, autorizá el fix concreto. Si falta una variable, cargá el valor en Cloud. No lo pegues en el prompt ni en un extracto del log. Qué puede hacer el token está en [Dejar que un agente despliegue con cuidado](https://unbroker.cloud/es/blog/coding-agent-deploy-safely). El flujo de deploy de ese agente está en [Desplegar con Claude Code](https://unbroker.cloud/es/desplegar/claude-code).

Pro sale $25 por mes, con $25 de crédito de uso. El crédito se reinicia en cada ciclo y no se acumula. Si el uso elegible queda por debajo del crédito, el cargo mensual sigue siendo el precio del plan. Las cifras actuales están en [precios](https://unbroker.cloud/es/precios).

## Checklist

1. Copiá el id del deployment y el id del servicio. Corré `ubctl whoami` y confirmá la organización.
2. Leé el log de ese deployment y después los logs de runtime de la misma ventana. Hacé coincidir el commit y el entorno.
3. Nombrá la etapa antes de cambiar un ajuste.
4. En un build, usá el primer error accionable. Revisá el acceso, el lockfile y la versión del runtime.
5. Si el proceso se cierra, revisá el comando de start, los archivos que faltan y las variables requeridas. Cargá en Cloud los valores que falten.
6. En un health check, revisá `PORT`, `0.0.0.0`, el path y si el proceso ya está escuchando.
7. Si el deployment está live y falla un endpoint, llamalo. Una respuesta sana no prueba una feature que depende del schema.
8. Si el error es de memoria, fijate si fue el build o el proceso en ejecución antes de cambiar la capacidad.
9. Si `postDeployStatus` es `failed`, el deployment puede seguir live. Leé la salida del comando. No se revirtió nada.
10. Desplegá con `--wait` y pedí el endpoint. Hacé rollback solo cuando promover un deployment conocido sea el arreglo más chico. Un rollback no restaura una base ni un volumen.

## Preguntas frecuentes

### ¿Por qué el build pasa y el deploy falla?

El artefacto se construyó. La falla es después, en el arranque o en el health check. Un health check fallido impide que esa revisión quede live. Leé los logs de runtime. Causas típicas de arranque: falta el script de start, no se generó el archivo compilado, o falta una variable que el proceso necesita para arrancar. El proceso también tiene que escuchar en 0.0.0.0 y en el PORT que recibe. Las fuentes son la [guía de Node.js](https://docs.unbroker.cloud/guides/deploy-nodejs) y el [overview de deployments](https://docs.unbroker.cloud/deployments/overview).

### ¿Qué significa que falló el health check?

La revisión nueva no respondió sana, así que no se trata como live. Revisá la dirección de escucha, el path del endpoint y la duración del arranque. El proceso tiene que escuchar en 0.0.0.0 y en el PORT que recibe, no solo en localhost. La documentación no publica una cantidad de segundos para esa espera. Esos chequeos están en [Diagnose a failed deployment](https://docs.unbroker.cloud/guides/debug-failed-deployment).

### ¿Alcanza con volver a desplegar?

No, si todavía no sabés la etapa. Repetir el deploy sin eso puede esconder evidencia útil. El overview de deployments dice que revises los logs de build y de runtime antes de reintentar. No describe un reintento automático.

### ¿Un rollback arregla una migración rota?

No. ubctl apps rollback promueve un deployment anterior y no reconstruye ese commit. No restaura una base, un volumen ni un efecto externo, y no deshace escrituras en la base. Ese límite está en [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy).

### Falló el comando post-deploy. ¿La app está caída?

No. El deployment sigue live y no se revierte nada. postDeployStatus queda en failed, y la salida del comando está en el log del deployment. El comando corre como máximo 10 minutos, requiere un plan pago y no está disponible para servicios de imagen. Mirá la [nota del 26 de octubre](https://unbroker.cloud/changelog/2026-10-26-post-deploy-command) y la [CLI de deployments](https://docs.unbroker.cloud/cli/deployments).

## Related reading

- [Desplegar con git push](https://unbroker.cloud/es/blog/deploy-on-git-push)
- [Migraciones de base de datos en el deploy](https://unbroker.cloud/es/blog/database-migrations-on-deploy)
- [Dejar que un agente despliegue con cuidado](https://unbroker.cloud/es/blog/coding-agent-deploy-safely)
- [Docker Compose en producción](https://unbroker.cloud/es/blog/docker-compose-to-production)
- [Desplegar con Claude Code](https://unbroker.cloud/es/desplegar/claude-code)
- [Precios](https://unbroker.cloud/es/precios)
- [Topes de deploy y de runtime en Free](https://unbroker.cloud/es/blog/free-backend-hosting)
