googleapis/mcp-toolbox · critical

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

This error is returned by the cloud-sql-mssql source's Initialize when the newly opened Cloud SQL SQL Server connection pool fails its initial health check (db.PingContext). It wraps the underlying driver error, so the real cause (network, auth, instance) is in the wrapped message. The pool is closed before returning, so no leaked connections remain.

Source

Thrown at internal/sources/cloudsqlmssql/cloud_sql_mssql.go:80

}

func (r Config) SourceConfigType() string {
	// Returns Cloud SQL MSSQL source type
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	// Initializes a Cloud SQL MSSQL source
	db, err := initCloudSQLMssqlConnection(ctx, tracer, r.Name, r.Project, r.Region, r.Instance, r.IPType.String(), r.User, r.Password, r.Database)
	if err != nil {
		return nil, fmt.Errorf("unable to create db connection: %w", err)
	}

	// Verify db connection
	err = db.PingContext(ctx)
	if err != nil {
		db.Close()
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Db:     db,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Db *sql.DB
}

func (s *Source) IsReadOnly() bool {
	return false

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify project, region, and instance values in the toolbox YAML match the Cloud SQL instance exactly
2. Check the instance is RUNNING in the Cloud SQL console and the Cloud SQL Admin API is enabled
3. If ipType is private, run the toolbox inside the same VPC (or switch to public)
4. Confirm user/password are correct by connecting with sqlcmd or another client
5. Inspect the wrapped error (%w) for the driver-level cause (timeout, auth, DNS)

Example fix

// before
kind: Source
name: my-mssql
type: cloud-sql-mssql
project: my-proj
region: us-central1
instance: wrong-instance-name
// after
kind: Source
name: my-mssql
type: cloud-sql-mssql
project: my-proj
region: us-central1
instance: my-instance  # exact instance name from `gcloud sql instances list`

gcloud sql instances describe INSTANCE_NAME --project=PROJECT --format='value(state,region)'

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
    var pingErr error
    if errors.Unwrap(err) != nil {
        pingErr = errors.Unwrap(err)
    }
    log.Fatalf("cloud-sql-mssql source failed to connect: %v (cause: %v)", err, pingErr)
}

When it happens

Trigger: Config.Initialize for a source of type 'cloud-sql-mssql' calls db.PingContext(ctx) and the ping fails — e.g. wrong project/region/instance coordinates, invalid ipType (private IP from a non-VPC network), bad user/password, unreachable instance, or the Cloud SQL Admin API not enabled.

Common situations: Typos in the instance connection name (project:region:instance), instance stopped or deleted, using ipType: private without running inside the same VPC, wrong SQL Server credentials, missing IAM/ADC permissions when connecting from Cloud Run/GKE, firewall or authorized-networks blocking egress.

Related errors

• unable to create db connection: %w
• unable to create pool: %w
• unable to connect successfully: %w
• sql.Open: %w
• unable to execute query: %w

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