---
title: Debug Failed Deployments
url: "/docs/debug/deploy-failures/"
canonical_url: https://docs.blossom88.com/docs/debug/deploy-failures/
markdown_url: https://docs.blossom88.com/docs/debug/deploy-failures.md
summary: Diagnose and correct failed Blossom deployments
categories:
- debugging
- deployment
- troubleshooting
---

# Debug Failed Deployments

A failed deployment preserves the previous healthy Release when Blossom can do
so safely. The failed Release, logs, health, and Activity should explain the
next customer action.

## Quick Diagnosis

1. Open the Environment and select the failed Release.
2. Read its failure summary and deployment logs.
3. Select the affected Service and inspect its Containers and health.
4. Review Environment Activity to distinguish an application failure from a
   condition Blossom will retry.

From the CLI:

```sh
blossom environment:show --id environment-100
blossom logs --environment environment-100
blossom environment:activity --id environment-100
blossom activity:show --id action-100
blossom activity:logs --id action-100
```

## Common Application Failures

### Startup Errors

Look for missing packages, invalid commands, image architecture errors, or an
application process that exits immediately. Reproduce the startup command
locally when possible.

### Missing Variables Or Secrets

Errors such as `Missing required environment variable` mean the Release cannot
start with its current configuration. Add the variable to the Environment,
review pending changes, and deploy again. Do not put secret values in source
control or support messages.

### Data Connection Errors

Verify the Database or Cache is healthy and linked to the Environment. Prefer
an Environment Link over copying a generated connection URL into Service
configuration.

### Port And Health Check Errors

Public Services must listen on `0.0.0.0` and the assigned `$PORT`. A health
endpoint should report application readiness without depending on optional
external systems. See [Web Service Port](/docs/debug/web-server-port/).

### Build Errors

Open the failed Build logs. Correct dependency, buildpack, Dockerfile, or
source-revision problems, then rebuild. A successful Build does not imply a
healthy runtime, so keep Build and Release evidence distinct.

## Retry Or Recover

Retry after correcting customer-owned input. Wait when Blossom marks a
temporary condition as retrying. Roll back when the current source or
configuration is unsafe and a known healthy Release exists.

If Blossom identifies a platform-owned delivery failure, include the App,
Environment, Release, and Activity identifiers when contacting support.