Cloud SQL Auth Proxy: failed to connect — IAM permission, API or IAM DB authentication problem

The proxy can't create a connection to the instance because of credentials, permissions or configuration.

Exact message you may see Cloud SQL Auth Proxy failed to connectcloud-sql-proxy: failed to connect to instance: Dial errorCloud SQL Admin API has not been used in project before or it is disabledgoogleapi: Error 403: Not authorized to access resource. Possibly missing permission cloudsql.instances.connectfailed to get instance: Refresh error
Seen on: Google Cloud

Meaning

Give the proxy's identity roles/cloudsql.client, enable the Cloud SQL Admin API, use the right instance connection name (project:region:instance), check IAM database authentication settings and database user type, and ensure the proxy reaches the instance's IP type (public/private).

Common causes

  • Missing cloudsql.client role
  • Cloud SQL Admin API disabled
  • Wrong instance connection name
  • IAM DB auth user not created
  • Private IP only but proxy outside the VPC

⚡ Quick fix

  1. Grant roles/cloudsql.client
  2. Enable sqladmin.googleapis.com
  3. Verify the connection name with gcloud sql instances describe

Detailed fix by platform

Shell

  1. bash
    gcloud services enable sqladmin.googleapis.com
    ./cloud-sql-proxy PROJECT:REGION:INSTANCE --private-ip

How to diagnose

  1. Role — cloudsql.client?
  2. API — Enabled?
  3. Connection name — Correct?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Platform & cloud. Errors that are often confused with or caused by this one (click to open):

10054 — SQL Server error 10054: An existing connection was forcibly closed by the remote host (SQL)1005440 — SQL Server Error 40: Could not open a connection to SQL Server (Named Pipes Provider) (SQL)40API has not been used in project before or it is disabled — Google Cloud: 403 SERVICE_DISABLED — Cloud Resource Manager API has not been used in project 123456 before or it is disabled. Enable it by visiting (Google Cloud / Firebase)API has not been used…BigQuery: Access Denied: Project: User does not have bigquery.jobs.create permission — BigQuery: Access Denied: Project my-project: User does not have bigquery.jobs.create permission in project my-project (Google Cloud / Firebase)BigQuery: Access Deni…Cloud Run 403: Your client does not have permission to get URL — Cloud Run: Error: Forbidden — Your client does not have permission to get URL / from this server (Google Cloud / Firebase)Cloud Run 403: Your c…Cloud SQL: failed to connect to instance — Cloud SQL: failed to connect to `host=PROJECT:REGION:INSTANCE user=app database=db`: dial error (timeout) / Cloud SQL Auth Proxy: failed to connect to instance (Google Cloud / Firebase)Cloud SQL: failed to …database flags — Cloud SQL: invalid database flag value / instance fails to restart after a flag change (Google Cloud / Firebase)database flagsGitHub trigger — Cloud Build trigger doesn't fire or fails: GitHub connection/app not installed or repository not linked (Google Cloud / Firebase)GitHub triggerAuth Proxy

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.