{"record":{"id":"98cdc780d96da628","repo":"googleapis/mcp-toolbox","slug":"unable-to-connect-successfully-w","errorCode":null,"errorMessage":"unable to connect successfully: %w","messagePattern":"unable to connect successfully: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/sources/alloydbpg/alloydb_pg.go","lineNumber":85,"sourceCode":"func (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 := initAlloyDBPgConnectionPool(ctx, tracer, r.Name, r.Project, r.Region, r.Cluster, 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.Ping(ctx)\n\tif err != nil {\n\t\tpool.Close()\n\t\tif r.ReadOnly &&\n\t\t\tstrings.Contains(err.Error(), \"unrecognized configuration parameter\") &&\n\t\t\tstrings.Contains(err.Error(), \"alloydb_session_read_only\") {\n\t\t\treturn nil, fmt.Errorf(\"failed to initialize AlloyDB source in read-only mode: 'alloydb_session_read_only' is not supported on this instance version. See documentation for details: https://mcp-toolbox.dev/integrations/alloydb/source/#reference: %w\", err)\n\t\t}\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 *pgxpool.Pool\n}\n\nfunc (s *Source) IsReadOnly() bool {\n\treturn s.ReadOnly","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/alloydbpg/alloydb_pg.go#L67-L103","documentation":"Generic connection failure for the alloydbpg source: the pool was created, but pool.Ping(ctx) failed and the error did not match the specific read-only-parameter case. This wraps the underlying pgx/alloydbconn error so any connectivity or authentication problem surfaces here.","triggerScenarios":"Any failed Ping after pool creation: wrong password, IAM principal not authorized as a database user, database does not exist, TLS/dial failure, instance stopped, or network unreachable.","commonSituations":"Instance stopped or under maintenance, password changed in IAM/Secret Manager but not the config, IAM authentication enabled on instance but the ADC principal isn't a Postgres user, firewall blocking 5432, private-IP instance reached from outside the VPC.","solutions":["Read the wrapped error for the specific cause (e.g. 'pq: password authentication failed', dial timeout).","Verify the instance is RUNNING: `gcloud alloydb instances describe <instance>`.","Check network reachability to the instance (VPC, PSA/PSC, firewall) for the chosen ipType.","Confirm username/password or IAM: the ADC principal must exist as a database user when IAM auth is used.","Verify the database name exists on the instance."],"exampleFix":"// before\nuser: app-user\npassword: old-password   # rotated\n// after\nuser: app-user\npassword: current-password  # or omit both to use IAM auth","handlingStrategy":"validation","validationCode":"# Pre-flight connectivity and auth checks before Initialize\nnc -vz -w 3 INSTANCE_IP 5432\ngcloud alloydb instances describe INSTANCE --cluster=C --region=R --format=\"value(state)\"  # expect RUNNING\npsql \"host=... user=... password=... dbname=... sslmode=require\" -c \"SELECT 1;\"","typeGuard":null,"tryCatchPattern":"src, err := cfg.Initialize(ctx, tracer)\nif err != nil && strings.Contains(err.Error(), \"unable to connect successfully\") {\n    // inspect wrapped cause; verify instance state, network path, and credentials\n    return fmt.Errorf(\"alloydb ping failed: %w\", err)\n}","preventionTips":["Monitor instance state (RUNNING) before connecting","Rotate credentials in config immediately after secret rotation","Verify the IAM principal exists as a Postgres user when using IAM auth","Test reachability for the configured ipType from the deployment network"],"tags":["go","alloydb","connection","authentication","network"],"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"}