Debug connection issues Stay organized with collections Save and categorize content based on your preferences.
Introduction
Generally, connection issues fall into one of the following three areas:
- Connecting - are you able to reach your instance over the network?
- Authorizing - are you authorized to connect to the instance?
- Authenticating - does the database accept your database credentials?
Each of those can be further broken down into different paths forinvestigation. The following section includes examples of questions you can askyourself to help further narrow down the issue:
Connection issues checklist
- Connecting
- Private IP
- Have youenabled the
Service Networking API
for your project? - Are youusing a Shared VPC?
- Does your user or service account have therequired IAM permissions to manage a private services access connection?
- Isprivate services access connection configured for your project?
- Did youallocate an IP address range for the private connection?
- Did yourallocated IP address ranges contain at least a /24 space for every region where you are planning to create postgres instances?
- If you are specifying anallocated IP address range for your postgres instances, does the range contain at least a /24 space for every region where you are planning to create postgres instances in this range?
- Is theprivate connection created?
- If the private connection was changed, were thevpc-peerings updated?
- Do theVPC logs indicate any errors?
- Is your source machine's IP anon-RFC 1918 address?
- Public IP
- Is your source IP listed as anauthorized network?
- Are SSL/TLS certificatesrequired?
- Does your user or service account have therequired IAM permissions to connect to a Cloud SQL instance?
- Authorizing
- Cloud SQL Auth Proxy
- Is the Cloud SQL Auth Proxyup to date?
- Is the Cloud SQL Auth Proxyrunning?
- Is the instanceconnection name formed correctly in theCloud SQL Auth Proxy connection command?
- Have you checked the Cloud SQL Auth Proxy output? Pipe the output to a file, or watch the Cloud Shell terminal where you started the Cloud SQL Auth Proxy.
- Does your user or service account have therequired IAM permissions to connect to a Cloud SQL instance?
- Have youenabled the
Cloud SQL Admin API
for your project? - If you have an outbound firewall policy, make sure it allows connections to port 3307 on the target Cloud SQL instance.
- If you are connecting using UNIX domain sockets, confirm that the sockets were created by listing the directory specified with the-dir when you started the Cloud SQL Auth Proxy.
- Cloud SQL connectors and language-specific code
- Is theconnection string formed correctly?
- Have you compared your code with thesample code for your programming language?
- Are you using a runtime or framework for which we don't havesample code?
- If so, have youlooked to the community for relevant reference material?
- Self-managed SSL/TLS certificates
- Is the client certificateinstalled on the source machine?
- Is the client certificate spelled correctly in theconnection arguments?
- Is the client certificatestill valid?
- Are you getting errors whenconnecting using SSL?
- Is the server certificatestill valid?
- Authorized networks
- Is thesource IP address included?
- Are you using anon-RFC 1918 IP address?
- Are you using anunsupported IP address?
- Connection failures
- Are youauthorized to connect?
- Are you seeingconnection limit errors?
- Is your applicationclosing connections properly?
- Authenticating
- Native database authentication (username/password)
- Are you seeing
access denied
errors? - Are theusername and password correct?
- IAM database authentication
- Have youenabled the
cloudsql.iam_authentication
flagon your instance? - Did youadd a policy binding for the account?
- Are you using the Cloud SQL Auth Proxy with the
-enable_iam_login
or an Oauth 2.0 token as the database password? - If using a service account, are you using theshortened email name?
- Learn more aboutIAM database authentication in PostgreSQL.
Error messages
For specific API error messages, see theError messages reference page.
Additional connectivity troubleshooting
For other issues, see theConnectivity section in the troubleshooting page.
Common connection issues
Verify that your application is closing connections properly
If you see errors containing "Aborted connection nnnn to db:
", it usuallyindicates that your application is not stopping connections properly. Network issues can also cause this error. The error does not mean thatthere are problems with your Cloud SQL instance. You are also encouraged to runtcpdump
to inspect the packets to track down the source of the problem.
For examples of best practices for connection management, seeManaging database connections.
Verify that your certificates have not expired
If your instance is configured to use SSL, go to theCloud SQL Instances pagein the Google Cloud console and open the instance. Open itsConnections page, select theSecurity tab and make sure that your server certificate is valid. If it has expired, you mustadd a new certificate and rotate to it.
Verify that you are authorized to connect
If your connections are failing, check that you are authorized to connect:
- If you are having trouble connecting using an IP address, for example,you are connecting from your on-premises environment with the psqlclient, then make sure that the IP address you are connecting fromis authorized to connectto the Cloud SQL instance.
Connections to a Cloud SQL instance using a private IP address areautomatically authorized forRFC 1918address ranges. This way, all private clients can access the databasewithout going through the Cloud SQL Auth Proxy. Non-RFC 1918 address ranges must be configuredasauthorized networks.
Cloud SQL doesn't learn Non-RFC 1918 subnet routes from yourVPC by default. You need to update the network peering to Cloud SQL to export anyNon-RFC 1918 routes. For example:
gcloudcomputenetworkspeeringsupdatecloudsql-postgres-googleapis-com\--network=NETWORK\--export-subnet-routes-with-public-ip\--project=PROJECT_ID
Here's yourcurrent IP address.
- Try the
gcloud sql connect
command to connect to your instance. This command authorizes your IP address for ashort time. You can run this command in an environment withgcloud CLI and psql client installed. You can also run this commandinCloud Shell, which is available in theGoogle Cloud console and hasgcloud CLI and the psql client pre-installed.Cloud Shell provides a Compute Engine instance that you can useto connect to Cloud SQL. - Temporarily allow all IP addresses to connect to an instance byauthorizing
0.0.0.0/0
.Note: Authorizing all IP addresses opens yourdatabase to any client that tries to connect. If you have sensitive orproprietary data in your database, don't use this method to investigateconnectivity issues.
Verify how you connect
If you get an error message like:FATAL: database `user` does not exist.
Thegcloud sql connect --user
command only works with the defaultuser (postgres
). The workaround is to connect using the default user, then usethe"\c"
psql command to reconnect as the different user.
Determine how connections are being initiated
You can see information about your current connections by connecting to yourdatabase and running the following command:
SELECT*frompg_stat_activity;
Connections that show an IP address, such as1.2.3.4
, are connecting using IP.Connections withcloudsqlproxy~1.2.3.4
are using the Cloud SQL Auth Proxy, or else theyoriginated from App Engine. Connections fromlocalhost
may beused by some internal Cloud SQL processes.
Connection limits
There are no QPS limits for Cloud SQL instances. However, there are connection,size, and App Engine specific limits in place. SeeQuotas and Limits.
Database connections consume resources on the server and the connectingapplication. Always use good connection management practices to minimizeyour application's footprint and reduce the likelihood of exceedingCloud SQLconnection limits.For more information, seeManaging database connections.
Show connections and threads
To see the processes that are running on your database, use thepg_stat_activity table:
select*frompg_stat_activity;
Connections timeout (from Compute Engine)
Connections with a Compute Engine instance timeout after 10 minutes ofinactivity, which can affect long-lived unused connections between yourCompute Engine instance and your Cloud SQL instance. For moreinformation, seeNetworking and Firewallsin the Compute Engine documentation.
To keep long-lived unused connections alive, you can set theTCP keepalive.The following commands set the TCP keepalive value to one minute and make theconfiguration permanent across instance reboots.
Display the current tcp_keepalive_time value.
cat/proc/sys/net/ipv4/tcp_keepalive_time
Set tcp_keepalive_time to 60 seconds and make it permanent across reboots.
echo'net.ipv4.tcp_keepalive_time = 60'|sudotee-a/etc/sysctl.conf
Apply the change.
sudo/sbin/sysctl--load=/etc/sysctl.conf
Display the tcp_keepalive_time value to verify the change was applied.
cat/proc/sys/net/ipv4/tcp_keepalive_time
Tools for debugging connectivity
Note: Tools that are based on the Internet Control Message Protocol (ICMP), suchasping
andtraceroute
, do not work with Cloud SQL.Do not use these tools for troubleshooting because they can return falsenegatives.tcpdump
Thetcpdump
is a tool to capture packets. It's highly encouraged to runtcpdump
to capture and inspect the packets between your host and the Cloud SQL instances when you are debugging the connectivity problems.
Locate your local IP address
If you don't know the local address of your host, then run theip -br address show
command. On Linux, this shows the network interface,the status of the interface, the local IP, and MAC addresses. For example:eth0 UP 10.128.0.7/32 fe80::4001:aff:fe80:7/64
.
Alternatively, you can runipconfig
orifconfig
to seethe status of your network interfaces.
Test with Connectivity Test
Connectivity Test is a diagnostics tool that lets you check connectivity between endpoints in your network. It analyzes your configuration and in some cases performs run-time verification. It supportsCloud SQL now. Followthese instructions to run tests with your Cloud SQL instances.
Test your connection
You can use the psql client to test your ability to connectfrom your local environment. For more information, seeConnecting the psql client using IP addresses andConnecting the psql client using the Cloud SQL Auth Proxy.
Determine the IP address for your application
To determine the IP address of a computer running your application so youcan authorize access to your Cloud SQL instance from that address,use one of the following options:
- If the computer is not behind a proxy or firewall, log in to the computer and use theWhat is my IP? site to determine its IP address.
- If the computer is behind a proxy or firewall, log in to the computer anduse a tool or service likewhatismyipaddress.comto determine its true IP address.
Open local ports
To verify that your host is listening on the ports you think it is, run thess -tunlp4
command. This tells you what ports are open andlistening.For example, if you have a PostgreSQL database running, then port 5432 should beup and listening. For SSH, you should see port 22.
All local port activity
Use thenetstat
command to see all the local port activity. Forexample,netstat -lt
shows all the currently active ports.
Connect to your Cloud SQL instance using telnet
To verify that you can connect to your Cloud SQL instance usingTCP
, runthetelnet
command. Telnet attempts to connect to the IP address andport you give it.
telnet 35.193.198.159 5432
.On success, you see the following: Trying 35.193.198.159... Connected to 35.193.198.159.
.
On failure, you see Trying 35.193.198.159... ^C.telnet
hangs until you force-close the attempt:
.
Client authentication
Client authentication is controlled by a configuration file, which is namedpg_hba.conf
(HBA stands for host-based authentication).
Make sure the replication connections section of thepg_hba.conf
file on the source database is updated to accept connections from theCloud SQL VPC's IP address range.
Cloud Logging
Cloud SQL and Cloud SQL use Cloud Logging. See theCloud Logging documentationfor complete information and review theCloud SQL sample queries.
View logs
You can view logs for Cloud SQL instances and other Google Cloudprojects such as Cloud VPN or Compute Engine instances. To view logs foryour Cloud SQL instance log entries:
Console
In the Google Cloud console, go to theCloud Logging page.
- Select an existing Cloud SQL project at the top of the page.
- In the Query builder, add the following:
- Resource: SelectCloud SQL Database. In the dialog, select a Cloud SQL instance.
- Log names: Scroll to the Cloud SQL section and select appropriate log files for your instance. For example:
- cloudsql.googleapis.com/postgres.log
- Severity: Select a log level.
- Time range: Select a preset or create a custom range.
gcloud
Use thegcloud logging
command to view log entries. In the example below, replacePROJECT_ID
.Thelimit
flag is an optional parameter that indicates the maximum number of entries toreturn.
gcloudloggingread"projects/PROJECT_ID/logs/cloudsql.googleapis.com/postgres.log"\--limit=10
Private IP addresses
Connections to a Cloud SQL instance using a private IP address areautomatically authorized forRFC 1918address ranges. Non-RFC 1918 address ranges must be configuredin Cloud SQL asauthorizednetworks. You also need to update the network peering to Cloud SQL toexport any Non-RFC 1918 routes. For example:
gcloudcomputenetworkspeeringsupdatecloudsql-postgres-googleapis-com
--network=NETWORK
--export-subnet-routes-with-public-ip
--project=PROJECT_ID
VPN troubleshooting
See theCloud VPN troubleshooting page.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-07-14 UTC.