googleapis/mcp-toolbox · error

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

This error is returned by the MSSQL source's `Config.Initialize` when `PingContext` fails after the sql.DB handle was created. It means the client could connect far enough to open but the live round-trip to SQL Server failed — typically network, auth, TLS, or server availability issues. The db handle is closed before returning.

Source

Thrown at internal/sources/mssql/mssql.go:78

}

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 MSSQL source
	db, err := initMssqlConnection(ctx, tracer, r.Name, r.Host, r.Port, r.User, r.Password, r.Database, r.Encrypt)
	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 host and port (default 1433) are reachable (telnet/nc test)
2. Check username/password and that SQL auth (or the right auth mode) is enabled
3. Review the Encrypt setting — try matching the server's TLS requirements or trust the server certificate
4. Check firewall rules (Azure SQL / local Windows Firewall) allow the client IP
5. Unwrap the error to distinguish login failure vs timeout vs TLS handshake

Example fix

// before (TLS handshake failure)
encrypt: "true"
// after (dev/test only — trust self-signed certs)
encrypt: "disable"  // or configure trust_server_certificate per driver options

func canReachSqlServer(host string, port int) error {
    conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), 5*time.Second)
    if err != nil {
        return err
    }
    return conn.Close()
}

src, err := cfg.Initialize(ctx, tracer)
if err != nil && strings.Contains(err.Error(), "unable to connect successfully") {
    time.Sleep(2 * time.Second) // backoff
    src, err = cfg.Initialize(ctx, tracer)
}

When it happens

Trigger: Calling Initialize when the server is unreachable (wrong host/port), credentials are rejected, TLS/Encrypt negotiation fails, firewall blocks port 1433, or the context deadline expires during the ping.

Common situations: SQL Server not accepting TCP/IP connections (only shared memory/named pipes); Azure SQL firewall rules denying the client IP; wrong password; Encrypt=true against a server without a trusted certificate; VPN/network not connected.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• unable to connect successfully: %w
• unable to connect successfully: %w
• toolbox failed to start listener: %w
• unable to connect successfully: %w
• unable to create db connection: %w

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