Troubleshoot a stuck Environment
Find the last Lifecycle phase that changed and distinguish queue, build, deployment, readiness, and teardown delays.
An Environment is stuck when its status and last-update time stop changing for longer than comparable work in the same installation. Lifecycle does not publish a universal phase timeout. Compare it with the local workload and operator expectations.
Find the last phase
Then use the status:
| Status | Examine |
|---|---|
pending | Feature policy, repository processing, and whether a worker queued work |
queued | Worker availability and whether other queued Environments change |
building | Service build history and the active build job |
deploying | Service deploy job, Kubernetes apply output, and readiness |
tearing_down | Cleanup worker output and remaining Environment state |
If the phase has a failure status, switch to build recovery or deployment recovery.
For a view of one Service:
Check the control plane
Operators can query /api/health on the affected component. A success response
confirms only Postgres and Redis connections. A worker /api/jobs response
does not confirm that jobs move through the queue.
Correlate web and worker logs with the Environment ID and request ID. Before you restart a component, examine the same worker phase for a different Environment. See Monitor Lifecycle for the documented probe boundaries and a safe escalation bundle.
Retry only after diagnosis
When one Service has a transient build or deploy problem, use a Service redeploy:
When the failure spans Services, use a full-Environment redeploy:
Another retry can multiply queued work and hide the first error. Do not restart all workers or delete queue data as a first response.