googleapis/mcp-toolbox · critical

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

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.

Source

Thrown at internal/sources/alloydbpg/alloydb_pg.go:85

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	pool, 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)
	if err != nil {
		return nil, fmt.Errorf("unable to create pool: %w", err)
	}

	err = pool.Ping(ctx)
	if err != nil {
		pool.Close()
		if r.ReadOnly &&
			strings.Contains(err.Error(), "unrecognized configuration parameter") &&
			strings.Contains(err.Error(), "alloydb_session_read_only") {
			return 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)
		}
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Pool:   pool,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Pool *pgxpool.Pool
}

func (s *Source) IsReadOnly() bool {
	return s.ReadOnly

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped error for the specific cause (e.g. 'pq: password authentication failed', dial timeout).
2. Verify the instance is RUNNING: `gcloud alloydb instances describe <instance>`.
3. Check network reachability to the instance (VPC, PSA/PSC, firewall) for the chosen ipType.
4. Confirm username/password or IAM: the ADC principal must exist as a database user when IAM auth is used.
5. Verify the database name exists on the instance.

Example fix

// before
user: app-user
password: old-password   # rotated
// after
user: app-user
password: current-password  # or omit both to use IAM auth

# Pre-flight connectivity and auth checks before Initialize
nc -vz -w 3 INSTANCE_IP 5432
gcloud alloydb instances describe INSTANCE --cluster=C --region=R --format="value(state)"  # expect RUNNING
psql "host=... user=... password=... dbname=... sslmode=require" -c "SELECT 1;"

src, err := cfg.Initialize(ctx, tracer)
if err != nil && strings.Contains(err.Error(), "unable to connect successfully") {
    // inspect wrapped cause; verify instance state, network path, and credentials
    return fmt.Errorf("alloydb ping failed: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• password is provided without a username. Please provide both
• unable to connect successfully: %w
• failed to discover OIDC config: %w
• failed to fetch OIDC config: %w
• failed to create Google tokeninfo request: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/98cdc780d96da628. Report an issue: GitHub.