Troubleshoot a failed build
Identify the failed Service build, examine the correct job logs, correct the source or build configuration, and check a redeploy.
A Build failed Service did not create the image or build artifact necessary for deployment. Start with build history and build logs. Pod logs give information about a deployed workload. They usually cannot identify this phase’s cause.
1. Find the failing phase
Open the Environment. Select the failed Service.
- Config error means Lifecycle could not accept or resolve the repository configuration. Correct the validation error first.
- Build failed means a native or external image build failed. Continue with the next steps.
- Deploy failed means the image was built but the workload could not be applied or become ready. Use Troubleshoot a failed deployment.
2. Read the failed build attempt
In the UI, open Console → Build. Select the newest failed attempt. Find the earliest actionable error. Later lines usually show a downstream error such as “job failed.”
From the CLI:
For a previous attempt, use --job <job-name>. While the current job runs, use
--follow.
3. Match the error to a cause
| Signal | Check |
|---|---|
| Repository or revision not found | GitHub App repository access, onboarding, repository spelling, branch, and SHA |
| Dockerfile or build context missing | dockerfile, context, and paths relative to the source repository |
| Base image or dependency denied | Registry credentials, image name, tag, network access, and rate limits |
| Build command or compiler error | The first source error and the revision shown for the attempt |
| No space, out of memory, or timeout | Builder capacity, resource limits, and context size |
| External pipeline failed | The linked pipeline run, configured pipeline ID, and provider authentication |
Do not copy credentials or full Environment-variable output into an issue. Share the Environment ID, Service name, job name, source SHA, engine, and the smallest redacted error excerpt.
4. Correct and retry
Commit source or lifecycle.yaml fixes to the owning branch. Lifecycle usually
queues the updated Service after the push. To retry unchanged inputs:
Another retry does not correct a deterministic configuration, source, credential, or capacity failure. Before you redeploy, read the first failed attempt.
5. Recovery check
The Service goes from Building to Built. Then, it goes through its deployment phase to Ready. If the build succeeds but deployment fails, switch to the deployment guide. Do not continue to examine build logs.