Understand the boundary between an image and a running revision
A container image is a packaged application. A Cloud Run revision combines that image with runtime configuration. A successful image build proves that packaging completed; it does not prove that the application can start with the selected environment, dependencies and port. Treat startup failure as a release acceptance problem before investigating load-balancing behavior.
For a service container, Google documents the required listening port supplied through the PORT environment variable and binding to an interface reachable by the runtime. A process listening only on its own loopback interface can work in a developer's narrow test and still fail the runtime contract. The service logs are the first place to look for an application error that occurs before a listener opens.
Prepare the first deployment
- Build an image for the runtime's supported platform and record its immutable digest. Keep the entry point and start command with the application source.
- Make the application read its runtime configuration, including the provided port, without embedding environment secrets in the image. Document which dependencies are necessary before it can serve traffic.
- Test startup in an isolated environment, record typical startup duration and configure readiness expectations around that evidence. Retain the previous working revision and its configuration.
The exact deploy command depends on the service's region, access policy and networking. Review those parameters with the application owner rather than copying a production command into an unrelated project.
Illustrative incident: the process starts but the revision fails
A Node.js service was changed to bind to 127.0.0.1. Its local health test contacts that same loopback interface and passes. A deployed revision never becomes ready. This is an illustrative training scenario. The diagnosis requires checking the actual listener; increasing a startup timeout does not make a loopback-only listener reachable.
Read evidence in execution order
Begin with the image digest and revision ID. Identify whether the entry point ran, whether configuration loading completed and whether a server began listening. Do not collapse those events into a single 'container broken' label.
| Observation | Next evidence | Likely investigation boundary |
|---|---|---|
| Process exits immediately | First application exception | Entry point or configuration |
| Process stays alive without readiness | Listener address and port | Runtime contract |
| Startup waits on a dependency | Timed dependency operation | Initialization design or connectivity |
For a local, non-production rehearsal, the pattern below passes a port explicitly and publishes it to the host. IMAGE_DIGEST must be an approved image reference; do not add secret values directly to shell history.
docker run --rm -e PORT=8080 -p 8080:8080 IMAGE_DIGEST
Inspect sanitized stdout and stderr. Test from outside the container, not only from a shell inside it. A successful local run still needs a managed-runtime rehearsal because identity and networking may differ.
Correct one boundary and keep rollback available
If the listener mismatch is demonstrated, correct it in source, rebuild and deploy a new revision. If startup is blocked by a dependency, decide whether that dependency is required for initial readiness or can be initialized later. Do not convert an initialization exception into a permanently successful health response; that can route requests to an unusable service.
Route a controlled test through the actual service endpoint and exercise a meaningful user operation. Compare failures and latency with the previous revision before expanding traffic. If acceptance fails, use the documented traffic-recovery procedure rather than rebuilding an older image from memory.
Define the operating contract
Use successful user requests as a service indicator and startup success as a release indicator. An illustrative release gate could require three cold-start rehearsals and one dependency-failure rehearsal to pass before approval. These are example internal criteria, not a Google SLA or measured Clouvenix outcome.
The SOP should name the release owner, image digest, revision, configuration change, observed startup result and reversal trigger. Escalate when a fix changes public access, identity or required dependencies. Review startup behavior whenever the framework, base image or entry point changes.
See Docker container engineering for related implementation scope.
Technical reference
Google Cloud: troubleshoot Cloud Run. Reviewed 19 October 2026; check the contract for the service and runtime you deploy.