---
cuppy_hub: gcp
cuppy_path: reference/databases/errors.md
cuppy_section: docs
cuppy_doc: 9CC5-SZGT
cuppy_doc_uuid: 24599a5d-eed1-482d-8ae1-037619ebc10b
cuppy_permalink: https://cuppy.io/gcp/d/9CC5-SZGT
cuppy_version: 1
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/gcp/docs/reference/databases/errors
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: cfe5700a5a2ce0eeb161d9db62fc9b651a458a027f662d3ccbcf06ca9bc0ef8d
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Database error catalogue

## 1. An honest note about verbatim strings

**The Cloud SQL pages read for this release publish no verbatim connection error messages.** So this catalogue
is indexed by **symptom and configuration** rather than by string, and it says so rather than inventing
plausible-looking messages. Engine-level errors (`FATAL:` from PostgreSQL, `ERROR 1045` from MySQL) come from
the engine, not from Google Cloud, and are documented by the engine's own project.

Where this hub *does* hold a verbatim string for a database-caused failure, it is a **Cloud Run** string —
§4 — because that is where the failure surfaces.

## 2. Cannot connect

| Symptom | Cause | Check | Fix |
|---|---|---|---|
| connection refused or hangs, from inside Google Cloud | the instance has **private IP** and the client is not on a network that reaches it | which connection path is configured? Is the client in the VPC, or reaching it over Private Service Connect / private services access? | put the client in the VPC, or use a **connector** |
| connection refused from outside Google Cloud, instance has a public IP | **authorized networks** does not include the caller | what is in the authorized-networks list? | the vendor's own recommendation: *"If you're connecting to an instance by a public IP address, use a Cloud SQL connector (either the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors)."* An allowlist of addresses is the weaker answer |
| the connector itself cannot connect | the client identity lacks **`roles/cloudsql.client`** | does the workload's service account hold it? | grant `roles/cloudsql.client`. This is an IAM failure wearing a database costume |
| authentication fails with a correct password | the user is an **IAM database authentication** user, not a built-in one — or the reverse | which authentication type is this user? Built-in uses a username and password; IAM uses a **short-lived access token** for an IAM principal | use the matching mechanism. A password will never work for an IAM user |

## 3. Available, then briefly not

| Symptom | Cause | Check | Fix |
|---|---|---|---|
| the instance restarted, apparently unprompted | a **maintenance update** — the one update category that "require[s] an instance restart", causing downtime | was it inside the configured maintenance window? | **schedule the window** at creation. If the restart itself is intolerable, that is the Enterprise Plus argument: it can achieve "sub-second downtime" |
| a failover happened | HA uses **a standby VM in another zone**; that is the mechanism working | — | ensure the client reconnects. A connection pool that does not retry turns a designed failover into an outage |

## 4. The cross-family row, and it is the most common of all

A Cloud Run service that cannot reach its database frequently presents as:

```
HTTP 503  The request failed because the instance could not start successfully.
```

whose documented causes include **missing secrets**, IAM, and network configuration. In practice the order to
check is:

1. can the runtime identity **read the secret** holding the connection details?
   `roles/secretmanager.secretAccessor`, not `roles/secretmanager.viewer`;
2. does it hold **`roles/cloudsql.client`**?
3. is the egress path to the database open?

See `reference/compute/errors.md` §4 and `patterns/cloud-run-to-cloud-sql-with-iam.md`.

## 5. Not an error: Bigtable's consistency changed under you

Adding a second **cluster** to a Bigtable instance changes it from **strongly consistent** to **eventually
consistent by default**. Nothing fails; reads simply become stale sometimes.

| Check | Fix |
|---|---|
| how many clusters does this instance have? | if more than one, configure **read-your-writes** or **strong** consistency explicitly — both are available and neither is the default |

This belongs in an error catalogue precisely because it produces no error. It is the hardest class of failure
to diagnose from a stack trace, and it is introduced by an availability change that looks unrelated.

Next: `guides/databases/connect-to-cloud-sql-with-iam-auth.md`, `guides/parity/databases.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 -->