Compute error catalogue — the Cloud Run startup failures, the deploy-time permission errors, 429 and 503
Cause, check and fix for the compute failures that come with a verbatim string: the container that did not listen on PORT, the container-import error, the two deploy permission errors, the image the service agent cannot read, and the two runtime statuses that mean capacity and startup.
markdownreferencev1AN1B-14HFstage: operatetrust: officialfamily: computeservice: cloud-runinterface: any"Container failed to start"PORT environment variablecontainer importUser does not have permission to access namespaceno available instancethe instance could not start successfully429503roles/run.sourceDeveloperroles/iam.serviceAccountUser
Compute error catalogue
1. The container did not start
Container failed to start. Failed to start and then listen on the port defined by the PORT environment variable.| cause | the process never listened where Cloud Run expects, or it exited |
| check | four things, in this order: does it run locally? does it bind the value of PORT rather than a hard-coded port? does it bind 0.0.0.0 rather than 127.0.0.1? is it a 64-bit Linux image? |
| fix | whichever of the four failed. Then read the application's own stdout/stderr in the logs — the page's own last resort and usually the fastest one |
The 127.0.0.1 case is the commonest and the least obvious: the container works locally because you are
inside it. Bind all interfaces.
2. The image could not be imported
The service has encountered an error during container import.| cause | the image's filesystem is not readable by the import step |
| check | non-UTF-8 characters in filenames; a Windows-built Docker image carrying foreign layers |
| fix | remove the non-UTF-8 filenames; rebuild on Linux |
3. Deploy-time permission errors — two different ones
User does not have permission to access namespace| cause | the deployer cannot act as the runtime identity, or the default Compute Engine service account has been deleted |
| check | does the deployer hold roles/iam.serviceAccountUser on the runtime service account? Does that account still exist? Does the deployer hold roles/run.sourceDeveloper for a source deploy? |
| fix | grant the role on the service account, and pass --service-account explicitly rather than relying on the default |
Cloud Run Service Agent must have permission to read the image| cause | the service agent — not you — cannot read the image |
| check | is the image in another project? Is there a VPC Service Controls restriction on the Cloud Storage API? |
| fix | grant the service agent read access on the image's repository; if VPC Service Controls is the cause, that is a perimeter decision, not a grant |
Both rows are the same lesson as reference/iac/config-connector.md §4: read the principal out of the
error. Three different identities appear in a Cloud Run deploy — you, the runtime service account, and the
service agent — and the fix is on whichever one the message names.
4. The two runtime statuses
HTTP 429 The request was aborted because there was no available instance.
HTTP 503 The request failed because the instance could not start successfully.| Status | Cause | Check | Fix |
|---|---|---|---|
| 429 | no instance was available: the maximum instance count or the scaling configuration | what is maximum instances set to, and was the service at it? | raise maximum instances, or review the scaling configuration. Retrying harder makes it worse |
| 503 | an instance tried to start and failed | missing secrets first, then IAM, then network | a 503 at steady state is nearly always a Secret Manager permission: the revision references a secret the runtime identity cannot access (reference/identity/secret-manager-and-kms.md §1 — the accessor role, not the viewer role). Then check egress rules |
The 429/503 pair is worth memorising together because they are read the same way by a monitoring dashboard and mean opposite things: 429 is capacity, 503 is configuration.
5. Where to go next
- the deploy walkthrough that avoids §1 and §3:
guides/compute/deploy-a-container-on-cloud-run.md - the identity behind §3:
guides/identity/fix-permission-denied.md - the secret behind most 503s:
reference/identity/secret-manager-and-kms.md - GKE and Compute Engine failures are not catalogued here; this family's error surface is Cloud Run's, which
is where a migrated container actually lands. Recorded as a gap in
changelog/2026-10-21-compute-family.md.