googleapis/mcp-toolbox · critical

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

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.

Source

Thrown at internal/sources/cloudsqlmysql/cloud_sql_mysql.go:80

	Database     string         `yaml:"database"`
	ReadOnly     bool           `yaml:"readOnly"`
	SQLCommenter *bool          `yaml:"sqlCommenter"`
}

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

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	pool, err := initCloudSQLMySQLConnectionPool(ctx, tracer, r.Name, r.Project, r.Region, 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.PingContext(ctx)
	if err != nil {
		pool.Close()
		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 *sql.DB
}

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. 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).
2. 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.
3. Ensure the runtime identity has roles/cloudsql.client and the Cloud SQL Admin API is enabled.
4. Test connectivity independently (e.g. cloud-sql-proxy or mysql client) to isolate toolbox config from infrastructure.
5. Check the database named in the config actually exists on the instance.

Example fix

// before
mySource:
  kind: source
  source: cloud-sql-mysql
  instanceConnectionName: proj-wrong:us-central1:inst
  user: app
  password: ${DB_PASS}
  database: nope
// after
mySource:
  kind: source
  source: cloud-sql-mysql
  instanceConnectionName: my-proj:us-central1:my-inst
  user: app
  password: ${DB_PASS}
  database: appdb

func checkCloudSQLConfig(instanceConnName, user, password, database string) error {
    if instanceConnName == "" || !strings.Contains(instanceConnName, ":") {
        return fmt.Errorf("instanceConnectionName must be project:region:instance, got %q", instanceConnName)
    }
    if user == "" || database == "" {
        return fmt.Errorf("user and database are required")
    }
    if password == "" {
        return fmt.Errorf("password is empty; check env var resolution")
    }
    return nil
}

func isConnectionError(err error) bool {
    var mysqlErr *mysql.MySQLError
    if errors.As(err, &mysqlErr) {
        switch mysqlErr.Number {
        case 1044, 1045, 1698:
            return true // access denied / auth required
        }
    }
    return strings.Contains(err.Error(), "dial") ||
        strings.Contains(err.Error(), "no such host") ||
        errors.Is(err, context.DeadlineExceeded)
}

src, err := source.Initialize(ctx)
if err != nil {
    var mysqlErr *mysql.MySQLError
    if errors.As(err, &mysqlErr) && mysqlErr.Number == 1045 {
        // bad credentials: rotate secret and re-init
    } else if strings.Contains(err.Error(), "unable to connect successfully") {
        // connectivity: check instance state, network, IAM before retrying
    }
    return err
}

When it happens

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

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

Related errors

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

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