Skip to content

Latest commit

 

History

History
104 lines (67 loc) · 2.7 KB

Troubleshooting.md

File metadata and controls

104 lines (67 loc) · 2.7 KB

Troubleshooting

If you encounter issues with cloudsqlctl, follow these steps to diagnose and resolve them.

The Doctor Command

The first step in troubleshooting is to run the built-in diagnostics tool:

cloudsqlctl doctor

This command checks:

  • Network Connectivity: Can you reach Google Cloud APIs?
  • Gcloud CLI: Is it installed and authenticated?
  • Credentials: Are Application Default Credentials (ADC) set up correctly?
  • Proxy Binary: Is the Cloud SQL Proxy binary present and executable?
  • Service Status: Is the Windows Service healthy (if installed)?

Common Issues

"Credential missing" or "Could not find default credentials"

Cause: The Cloud SQL Proxy requires Application Default Credentials (ADC) to authenticate with the Google Cloud API.

Solution: Run the following command to generate the ADC file:

cloudsqlctl auth adc

Or manually: gcloud auth application-default login

"Instance not found" or "403 Forbidden"

Cause: The active project selected in gcloud might be incorrect, or your account doesn't have permissions for the instance.

Solution:

  1. Check your active project:

    gcloud config get-value project

  2. Switch projects if necessary:

    cloudsqlctl setup
# OR
gcloud config set project <PROJECT_ID>

  3. Ensure your user has the Cloud SQL Client role.

Proxy fails to start

Cause: Port conflicts (default 5432 for Postgres, 3306 for MySQL) or invalid configuration.

Solution:

  1. Check the logs for detailed error messages:

    cloudsqlctl logs

  2. Try running the proxy in the foreground to see immediate output:

    cloudsqlctl start --foreground

Service fails to start (Error 1053)

Cause: Usually due to missing credentials or incorrect binary path.

Solution:

  1. Ensure you have set a Service Account key with --scope Machine: 
    cloudsqlctl auth set-service-account --file <path> --scope Machine
  2. Check the Windows Event Viewer (System logs) for specific service errors.
  3. Verify the service configuration: 
    cloudsqlctl service status

Resetting Configuration

If your configuration is corrupted, you can reset the tool to its default state:

cloudsqlctl reset

Warning: This will remove your local configuration files and the downloaded proxy binary. You will need to run cloudsqlctl setup again.

Getting Help

If you still have issues, please open an issue on our GitHub Repository with the output of cloudsqlctl doctor and cloudsqlctl logs.