---
cuppy_hub: gcp
cuppy_path: reference/compute/errors.md
cuppy_section: docs
cuppy_doc: AN1B-14HF
cuppy_doc_uuid: 1279911e-456c-4ff3-b808-4e3e289b5a51
cuppy_permalink: https://cuppy.io/gcp/d/AN1B-14HF
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/gcp/docs/reference/compute/errors
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: d79ea68a08e3fae903f274899391f471afab1c4a2ff59e739c2d73a14ec7649a
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# 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`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 91 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/gcp/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->