Troubleshoot a failed deployment

When an Environment shows Config error or Error, use this workflow. Also use this workflow when a Service shows Deploy failed or Error. If a Service shows Build failed, use Troubleshoot a failed build.

Resolve a Config error first

A Config error happens before Lifecycle can run the affected Services. A failed Service or Console does not always exist.

1. Read the Config error in the Environment metadata.

2. Check Current branch schema.

   • Invalid: Correct lifecycle.yaml using the schema reference.
   • Valid now: The branch is correct, but the Environment continues to record the earlier failed snapshot.

3. When the branch is valid, select Actions.

4. Select Redeploy.

For a static Environment, an administrator must do this action.

Find the first useful failure reason

For an Environment-level Error or a Service failure:

1. Open Environments in Lifecycle.
2. Select the affected Environment.
3. If the Environment shows Error, hover over or focus that status to read the Environment failure message.
4. If a Service shows Build failed, Deploy failed, or Error, select it from the Service list. The UI shows failed Services before healthy Services.
5. Before you open longer logs, read the Service Failure reason on the Summary tab.

If no Service failed, use the Environment failure message as the primary evidence. Then, escalate it. Service Console logs might not exist.

The summary tells you which Service failed. It identifies the cause or narrows the failure to a phase. For example, a Failure reason such as Kubernetes apply job failed identifies the deployment phase, but not the root cause. Open the Deploy logs to find the actionable error before retrying.

Open the related logs

For a failed Service, select Console. Then, use the phase that matches its status.

• Build failed: Select Build. Open the failed build attempt.
• Deploy failed: Select Deploy. Open the failed deployment attempt.
• Error: Start with the Failure reason. Then, examine Build or Deploy for the last completed phase.
• Ready, but the application is unhealthy: Select Pods to examine the running container logs.

A red dot on Build or Deploy marks the failed phase. If Lifecycle uses an external pipeline for that phase, the Console can show a link to its logs as an alternative to native job logs.

Look for the earliest actionable error, not all symptoms that follow it. Do not include tokens, secret values, or full environment-variable output when sharing logs.

Correct the cause

Use the Environment message or Service failure reason and logs to check the failed phase:

If the failure comes from repository content, commit the correction. Push the correction before you retry.

Redeploy

After correcting the cause:

1. To retry one Service, select the circular-arrow Redeploy control on its row.
2. To retry the full Environment, select Actions, then Redeploy.
3. Make sure that Lifecycle queues the redeploy.
4. Wait until the Environment shows Deployed.
5. Make sure that each necessary Service shows Ready.

If you changed shared configuration or more than one Service, use a full Environment redeploy. A redeploy reuses the current source and configuration. Thus, it does not correct a deterministic error by itself.

Lifecycle disables full redeploy for non-administrators on a static Environment. Administrators must enter redeploy.

Escalate with useful evidence

If the corrected deployment continues to fail, give your platform team:

• Environment ID and, when applicable, Service name
• Current status and the Environment failure message or Service Failure reason
• If Build, Deploy, or Pods contains the related error
• Commit short SHA and approximate failure time
• The smallest log excerpt that includes the actionable error

Do not include credentials, tokens, secret values, or unrelated application data.