googleapis/mcp-toolbox · critical

unable to create db connection: %w

Error message

unable to create db connection: %w

What it means

This error is thrown from the Cloud SQL MSSQL source's Config.Initialize when initCloudSQLMssqlConnection fails to establish a SQL Server connection via the Cloud SQL Go Connector. It wraps the underlying dial/auth error, meaning the toolbox could not open a database connection for the configured project/region/instance/user.

Source

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

	Project  string         `yaml:"project" validate:"required"`
	Region   string         `yaml:"region" validate:"required"`
	Instance string         `yaml:"instance" validate:"required"`
	IPType   sources.IPType `yaml:"ipType" validate:"required"`
	User     string         `yaml:"user" validate:"required"`
	Password string         `yaml:"password" validate:"required"`
	Database string         `yaml:"database" validate:"required"`
}

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{}

View on GitHub (pinned to 8cc6e09de2)

Solutions

  1. Check the wrapped cause: dial tcp errors indicate network/IP-type issues; auth errors indicate bad user/password or IAM credentials
  2. Verify project, region, and instance names in the source config match the actual Cloud SQL instance
  3. Ensure credentials have roles/cloudsql.client and Cloud SQL Admin API is enabled; set GOOGLE_APPLICATION_CREDENTIALS correctly
  4. Match ipType to the instance's connectivity (public vs private) and confirm the instance is RUNNING

Example fix

// before
sources:
  my-mssql:
    kind: cloud-sql-mssql
    project: my-prj
    region: us-centra1
    instance: my-instance
// after
sources:
  my-mssql:
    kind: cloud-sql-mssql
    project: my-prj
    region: us-central1
    instance: my-instance
Defensive patterns

Strategy: validation

Validate before calling

// Preflight before building the source config
if project == "" || region == "" || instance == "" || user == "" || password == "" {
    return errors.New("cloud-sql-mssql source requires project, region, instance, user, password")
}
// Verify ADC credentials are available
if _, err := google.FindDefaultCredentials(ctx, cloudsqlscope...); err != nil {
    return fmt.Errorf("no application default credentials: %w", err)
}

Try / catch

src, err := cfg.Initialize(ctx, tracer)
if err != nil {
    var opErr *net.OpError
    if errors.As(err, &opErr) {
        log.Printf("network failure connecting to Cloud SQL MSSQL: %v", opErr)
    }
    return err // wrapped: "unable to create db connection: ..."
}

Prevention

When it happens

Trigger: Config.Initialize is called with a bad project/region/instance combination, wrong IP type, invalid credentials (user/password or IAM auth), unreachable Cloud SQL instance, missing Cloud SQL Admin API permissions for the connector, or the connector failing to fetch an ephemeral certificate.

Common situations: Typo in instance or region in the source YAML; instance private-IP only while ipType is public; wrong username/password; service account lacking roles/cloudsql.client; instance stopped; Workload Identity or ADC credentials not present in the environment.

Related errors

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