The short answer

A failed deployment stops in one stage. Name that stage from the evidence it left, then change the smallest thing that explains it. A redeploy before you know the stage can hide that evidence.

Unbroker records the commit, the build output, the rollout, and the final health state. The finer split, from a clone error through a post-deploy command, is how you read a single failure. The walkthrough for an agent is Diagnose a failed deployment.

The stages a deployment goes through

A deployment turns a source revision into a running service. The deployments overview lists four stages:

  1. Queued. The deployment is accepted and assigned to the build system.
  2. Building. Dependencies are installed and the production artifact or image is created.
  3. Deploying. The new revision is rolled out and checked for health.
  4. Live. Traffic can reach the healthy revision.

A failed health check prevents an unhealthy revision from being treated as live. Review the build and runtime logs before you retry. The overview does not describe an automatic retry, and it does not describe an automatic rollback.

If the push never queued a deployment, the failure is earlier than these four stages. Which branch deploys, which paths count, and when Unbroker waits for checks is Deploy on git push. The wait itself is Wait for CI.

To follow one deployment until it finishes:

ubctl apps deploy <serviceId> --wait

--wait polls until the deployment reaches a terminal state and returns a non-zero exit code when it fails. That behavior is in the deployments CLI.

Deployment log vs runtime logs

The deployment output describes the build and the release attempt. Service logs describe the running process. Confirm the timestamps and the source revision so you are not reading an older deployment or another environment.

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

Replace the placeholders with the ids from that failure. ubctl whoami confirms the active organization before you read anything else. These commands are the gather step in the debug guide.

Logs, metrics, and monitoring separates the same signals. How those signals become alerts, and what they do not catch, is Logs, metrics and alerts. The build log says why a revision did or did not build. The runtime log is what the running application writes. Deployment history says what changed and which revision is live. Runtime lines are kept for 7 days. Build output is kept with each deployment. Build output older than 90 days is removed, except for the deployment the service is currently running. A later deploy is a new record. Reading the wrong commit, the wrong time, or another environment is how the evidence gets hidden.

Classify the failure

StageUseful evidenceTypical next check
Source or dependency installationClone and install errorsRepository access, the lockfile, and the dependency source
CompilationThe first actionable compiler or build errorBuild command, runtime version, and expected output
StartupThe process exit and the first runtime exceptionStart command, missing files, or required variables
Health or routingListening address and the probe responsePORT, 0.0.0.0, the endpoint path, and startup duration
Application requestHTTP status and the error for that requestDatabase connectivity, migrations, or application logic
Post-deploy commandpostDeployStatus: failed while the deployment stays live, plus the command output in the deployment log. If the control plane stops during the command, the same status is recorded and the command is not run againThe command, its timeout, and the service’s environment variables. The release is not rolled back

The table is the one in the debug guide. Memory exhaustion is not its own row. Treat it as evidence, and check whether it happened while building or while running before you change a setting. Those are different stages.

Build failures: dependencies and compilation

A build failure stays in Building. The deployment never reaches a health check.

Start with repository access, the lockfile, and where dependencies come from. The Node.js guide says to commit the lockfile your package manager produced. If the build installs private packages, the Docker guide says to pass the token as a BuildKit secret, under the name the tool expects. Tokens are not supplied as build arguments.

Use the first actionable compiler or build error. Then check the build command, the runtime version, and whether the expected output exists. On a very large build log, Unbroker keeps the beginning and the most recent output, so the last line is not the only place to look. That retention rule is in the monitoring docs.

For Bun, a repository with bun.lock or bun.lockb at its root is installed and built with Bun. Unless you pin a version, builds use Bun 1.4.2. An exact pin is read from "packageManager" in package.json, then a .bun-version file, then "engines". The [email protected] string in the docs is an example of an exact pin, not the default. Only exact versions from 1.2.0 up are honored. A range such as >=1.1 uses the default. The build log says which version was used and why. A server whose start command uses Bun runs on that same version. The source is service types.

A Dockerfile build uses the base image in that file. The Docker guide’s example is FROM node:22-slim. That tag is the example, not a platform default. The Fastify guide says to check that the selected Node.js version meets what the installed Fastify version requires.

Startup failures: the process exits

The image exists, and the process exits before it can serve. The evidence is that exit and the first runtime exception. Check the start command, missing files, and variables the process requires.

The Node.js guide names three typical causes: a missing start script, a compiled file that was never generated, and an environment variable required during startup. A TypeScript app needs a build that produces JavaScript and a start command that points at that output. The Fastify guide says to inspect the first startup error before retrying. The FastAPI guide says an import error usually means the module path does not match the repository, or a dependency was left out, and to read runtime logs before you increase resources.

If a variable is missing, set it in Cloud. Do not put the value in a prompt or in a copied log. Environment variables is that step.

Health check and routing failures

Deploying includes the health check. A failed check keeps that revision from being treated as live.

The process has to listen on 0.0.0.0 and the supplied PORT, not on a hard-coded localhost address. The Node.js guide says a successful build alone does not prove the server is reachable. EXPOSE in a Dockerfile does not start a server or publish a port. The listener does. Binding only to localhost is a common gap between a process that works on your machine and a container nothing can reach. That sentence is in the Fastify guide.

The other checks are the endpoint path and startup duration. If the probe calls a path the app does not serve, the check fails. On Pro, the Fastify guide says to point the service health check at /health when that is the route. Plans lists advanced health checks as not available on Free and available on Pro. The docs do not publish a number of seconds for how long startup may take. If the process is still coming up when the probe runs, read the runtime log for the first exception before you change the path.

A process with no listener should not be forced through an HTTP health check. Use a worker. The background worker guide says Dockerfile workers run without a public URL and without an HTTP readiness probe. How a Compose file maps onto those services is Docker Compose in production.

It deployed, but requests fail

Live means the health check passed and traffic can reach that revision. It does not mean every route works. After the deployment is live, request the endpoint you care about and read the response.

If the default Unbroker hostname answers and only the custom domain fails, the deployment is already live. DNS, hostname verification, and the certificate are the three states in Custom domain and HTTPS. Redeploying the same commit does not fix that.

A successful health response does not prove a schema-dependent feature works. The Fastify guide says the example health route does not prove a database is available. The Next.js guide says a homepage that renders does not exercise the whole application. The next checks are database connectivity, migrations, and application logic.

Migrations are their own release step. Where that command runs, and why a rollback leaves the schema in place, is Database migrations on deploy.

Out of memory: building or running?

Treat memory exhaustion as evidence. Check whether it happened during the build or while the process was running before you change a setting. The debug guide separates those stages.

If the build runs out of memory, the Next.js guide says to see where: dependency installation, compilation, or page generation. Reduce work the build does not need, or adjust the capacity that applies to that stage. Extra runtime replicas do not fix a build that ran out of memory. The FastAPI guide says to read the runtime logs before increasing resources, which is the other stage: the process is already running.

On Pro, the Resources tab shows CPU and memory against the limits the service runs with. Resource metrics are a Pro feature. CPU and memory limits are fixed on Free and configurable on Pro. Those rows are in Plans. The command that changes the running limit is in scaling. Use it after the log says the running process is the stage that ran out of memory.

Post-deploy command failed

A repository service can run one command after the deployment is already live. It runs in a one-off copy of the new image, with that service’s environment variables, for at most 10 minutes. The output is appended to the deployment log.

If the command fails, the deployment stays live and nothing is rolled back. postDeployStatus is running, succeeded, or failed. The command does not run when the deploy itself fails. If the control plane stops while the command is running, the same failure is recorded once the deploy lease expires, and the command is not started again.

The command does not mount a persistent volume. On-demand services do not need to be awake for it, and a private access gate does not apply to that one-off copy. Put secrets in environment variables, not in the command string. The command itself is not printed in the log, and long environment values are masked.

Post-deploy commands require a paid plan and are not available for image services. ubctl and infrastructure as code do not accept the field yet. @unbroker/iac v0.2.0 has preDeploy only. Set postDeployCommand in the service settings, or with PATCH /apps/services/:id. Changing the command marks the service for redeploy. The sources are the deployments CLI and the October 26 note.

Recover: fix forward or roll back

Fix the cause you found, then deploy again and wait:

ubctl apps deploy <serviceId> --wait

Request the affected endpoint. Confirm the original failure is gone. A healthy response still does not prove a schema-dependent feature. Include a check that hits that feature.

A rollback is the other recovery, and it is a command you run. The docs do not describe Unbroker starting one on its own.

ubctl apps rollback svc_123 dep_previous

In the docs, svc_123 and dep_previous stand for the service and the deployment you are promoting. A rollback promotes a known deployment. It does not rebuild the source commit. It does not restore a database, a volume, or an external side effect. Rolling back an image also does not undo configuration changes or database writes. Check the schema and the data before you choose it. Those sentences are in the deployments CLI, the debug guide, and infrastructure as code. What that means for a migration is Database migrations on deploy. A file that disappeared is a different failure from a crash. If it lived only on the container filesystem, Persistent storage volumes covers what survives a redeploy, and what Reset, Detach, and deleting the service remove.

On Free, deploy requests are 3 per UTC day. Unused deploys do not carry forward. Pro has no plan request cap. That row is in Plans. It is one reason to classify the stage first. The other limits on that plan, including sleep and the service cap, are Free plan deploy and runtime limits.

Doing it on Unbroker

The project view shows live logs, health, and deployment history for each service. Metrics are on Pro. Runtime logs are available on Free and on Pro. The commands above need an API token, and API tokens require Pro. Eligible public Node.js apps can be created in Cloud on Free. The Node.js guide states that split.

A coding agent can read the same evidence with the ubctl-ops skill. While it is diagnosing, it should not change resources. The prompt in the debug guide is:

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.

When the diagnosis holds, authorize the specific fix. If a variable is missing, enter the value in Cloud. Do not paste it into the prompt or into a log excerpt. What the token is allowed to do is in Letting a coding agent deploy safely. The deploy flow for that agent is Deploy with Claude Code.

Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Current figures are on pricing.

Checklist

  1. Copy the deployment id and the service id. Run ubctl whoami and confirm the organization.
  2. Read that deployment’s log, then the runtime logs for the same window. Match the commit and the environment.
  3. Name the stage before you change a setting.
  4. For a build, use the first actionable error. Check access, the lockfile, and the runtime version.
  5. For a process that exits, check the start command, missing files, and required variables. Set missing values in Cloud.
  6. For a health check, check PORT, 0.0.0.0, the path, and whether the process is listening yet.
  7. If the deployment is live and a request fails, call that endpoint. A healthy response does not prove a schema-dependent feature.
  8. If the error is memory, see whether it was the build or the running process before you change capacity.
  9. If postDeployStatus is failed, the deployment can still be live. Read the command output. Nothing was rolled back.
  10. Deploy with --wait and request the endpoint. Roll back only when promoting a known deployment is the smaller fix. A rollback does not restore a database or a volume.

FAQ

Why does my app build but fail to deploy?

The artifact was built. The failure is later, in startup or in the health check. A failed health check keeps that revision from being treated as live. Read the runtime logs. Typical startup causes are a missing start script, a compiled file that was never generated, or a variable the process needs in order to start. The process also has to listen on 0.0.0.0 and the supplied PORT. The sources are the Node.js guide and the deployments overview.

What does health check failed mean?

The new revision did not respond as healthy, so it is not treated as live. Check the listening address, the endpoint path, and startup duration. The process should listen on 0.0.0.0 and the supplied PORT, not only on localhost. The docs do not publish a number of seconds for that wait. Those checks are named in Diagnose a failed deployment.

Should I just redeploy?

Not before you know the stage. Repeated redeploys without that can hide useful evidence. The deployments overview says to review build and runtime logs before retrying. It does not describe an automatic retry.

Does a rollback fix a broken migration?

No. ubctl apps rollback promotes a previous deployment and does not rebuild that commit. It does not restore a database, a volume, or an external side effect, and it does not undo database writes. Database migrations on deploy is that limit.

My post-deploy command failed. Is my app down?

No. The deployment stays live and nothing is rolled back. postDeployStatus is failed, and the command output is in the deployment log. The command runs for at most 10 minutes, requires a paid plan, and is not available for image services. See the October 26 note and the deployments CLI.