{"record":{"id":"20066651a1c27184","repo":"googleapis/mcp-toolbox","slug":"unable-to-connect-successfully-w-200666","errorCode":null,"errorMessage":"unable to connect successfully: %w","messagePattern":"unable to connect successfully: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/sources/cloudsqlmysql/cloud_sql_mysql.go","lineNumber":80,"sourceCode":"\tDatabase     string         `yaml:\"database\"`\n\tReadOnly     bool           `yaml:\"readOnly\"`\n\tSQLCommenter *bool          `yaml:\"sqlCommenter\"`\n}\n\nfunc (r Config) SourceConfigType() string {\n\treturn SourceType\n}\n\nfunc (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {\n\tpool, err := initCloudSQLMySQLConnectionPool(ctx, tracer, r.Name, r.Project, r.Region, r.Instance, r.IPType.String(), r.User, r.Password, r.Database, r.ReadOnly)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to create pool: %w\", err)\n\t}\n\n\terr = pool.PingContext(ctx)\n\tif err != nil {\n\t\tpool.Close()\n\t\treturn nil, fmt.Errorf(\"unable to connect successfully: %w\", err)\n\t}\n\n\ts := &Source{\n\t\tConfig: r,\n\t\tPool:   pool,\n\t}\n\treturn s, nil\n}\n\nvar _ sources.Source = &Source{}\n\ntype Source struct {\n\tConfig\n\tPool *sql.DB\n}\n\nfunc (s *Source) IsReadOnly() bool {\n\treturn s.ReadOnly","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/cloudsqlmysql/cloud_sql_mysql.go#L62-L98","documentation":"This error wraps the failure of the initial PingContext on a newly created Cloud SQL MySQL connection pool during Source.Initialize. It means the toolbox created a sql.DB pool but could not get a working connection to the Cloud SQL MySQL instance (or the Unix socket/TCP endpoint) within the context deadline. The pool is closed and initialization aborts, so the source cannot serve any tools.","triggerScenarios":"Calling Initialize for a cloudsqlmysql source where pool.PingContext returns an error: wrong instance connection name, unreachable instance, bad user/password, database does not exist, IAM auth misconfigured, or the Cloud SQL Admin API / connector cannot dial the instance.","commonSituations":"Typos in the Cloud SQL instance connection name (project:region:instance), instance stopped or deleted, service account lacking Cloud SQL Client role, no private IP/VPC access from the runtime, database or user not created, password rotated, missing IAM DB authentication flag on the instance.","solutions":["Verify the instance connection string (project:region:instance), that the instance is RUNNING, and that the network path exists (Authorized Networks / private IP + VPC connector / Cloud SQL connector enabled).","Confirm credentials: user exists, password is correct, or IAM DB auth is properly enabled and the account name format (e.g. service account email) is right.","Ensure the runtime identity has roles/cloudsql.client and the Cloud SQL Admin API is enabled.","Test connectivity independently (e.g. cloud-sql-proxy or mysql client) to isolate toolbox config from infrastructure.","Check the database named in the config actually exists on the instance."],"exampleFix":"// before\nmySource:\n  kind: source\n  source: cloud-sql-mysql\n  instanceConnectionName: proj-wrong:us-central1:inst\n  user: app\n  password: ${DB_PASS}\n  database: nope\n// after\nmySource:\n  kind: source\n  source: cloud-sql-mysql\n  instanceConnectionName: my-proj:us-central1:my-inst\n  user: app\n  password: ${DB_PASS}\n  database: appdb","handlingStrategy":"validation","validationCode":"func checkCloudSQLConfig(instanceConnName, user, password, database string) error {\n    if instanceConnName == \"\" || !strings.Contains(instanceConnName, \":\") {\n        return fmt.Errorf(\"instanceConnectionName must be project:region:instance, got %q\", instanceConnName)\n    }\n    if user == \"\" || database == \"\" {\n        return fmt.Errorf(\"user and database are required\")\n    }\n    if password == \"\" {\n        return fmt.Errorf(\"password is empty; check env var resolution\")\n    }\n    return nil\n}","typeGuard":"func isConnectionError(err error) bool {\n    var mysqlErr *mysql.MySQLError\n    if errors.As(err, &mysqlErr) {\n        switch mysqlErr.Number {\n        case 1044, 1045, 1698:\n            return true // access denied / auth required\n        }\n    }\n    return strings.Contains(err.Error(), \"dial\") ||\n        strings.Contains(err.Error(), \"no such host\") ||\n        errors.Is(err, context.DeadlineExceeded)\n}","tryCatchPattern":"src, err := source.Initialize(ctx)\nif err != nil {\n    var mysqlErr *mysql.MySQLError\n    if errors.As(err, &mysqlErr) && mysqlErr.Number == 1045 {\n        // bad credentials: rotate secret and re-init\n    } else if strings.Contains(err.Error(), \"unable to connect successfully\") {\n        // connectivity: check instance state, network, IAM before retrying\n    }\n    return err\n}","preventionTips":["Validate instanceConnectionName format (project:region:instance) against the Cloud SQL console before deploying.","Keep the instance RUNNING and pin a health check (gcloud sql instances describe) in your deploy pipeline.","Grant the runtime service account roles/cloudsql.client and enable the Cloud SQL Admin API.","Pre-create the database and user; store the password in a secret manager, not a literal.","Smoke-test connectivity with cloud-sql-proxy or a mysql client from the same network before starting the toolbox."],"tags":["mysql","cloudsql","connection","database"],"backgroundTag":"database-connection-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}