googleapis/mcp-toolbox · error

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

After successfully creating the pgx pool, YugabyteDB Config.Initialize calls pool.Ping(ctx) to verify live connectivity. A failed ping — server unreachable, auth rejected, TLS mismatch, DNS failure — closes the pool and returns 'unable to connect successfully: %w'. Unlike 1027, the pool config was valid but no database could actually be reached.

Source

Thrown at internal/sources/yugabytedb/yugabytedb.go:74

	YBServersRefreshInterval        string `yaml:"ybServersRefreshInterval"`
	FallBackToTopologyKeysOnly      string `yaml:"fallbackToTopologyKeysOnly"`
	FailedHostReconnectDelaySeconds string `yaml:"failedHostReconnectDelaySecs"`
}

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

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	pool, err := initYugabyteDBConnectionPool(ctx, tracer, r.Name, r.Host, r.Port, r.User, r.Password, r.Database, r.LoadBalance, r.TopologyKeys, r.YBServersRefreshInterval, r.FallBackToTopologyKeysOnly, r.FailedHostReconnectDelaySeconds)
	if err != nil {
		return nil, fmt.Errorf("unable to create pool: %w", err)
	}

	err = pool.Ping(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 *pgxpool.Pool
}

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Test connectivity: 'psql -h <host> -p <port> -U <user> -d <database>' with the same credentials
2. Verify the Yugabyte cluster is running and reachable (docker network, VPC, firewall rules)
3. Check username/password/database are correct for the target cluster
4. Add correct TLS/sslmode configuration if the server requires TLS
5. Read the wrapped '%w' cause to distinguish auth failure vs network failure

Example fix

// before
sources:
  yugabyte:
    kind: yugabytedb
    host: 127.0.0.1
    port: 5433
    database: wrongdb
// after
sources:
  yugabyte:
    kind: yugabytedb
    host: 127.0.0.1
    port: 5433
    database: yugabyte

// Pre-flight connectivity check using the same credentials
import net from "net";
const s = net.createConnection({ host: cfg.host, port: cfg.port });
s.setTimeout(5000);
s.on("connect", () => { console.log("reachable"); s.end(); });
s.on("error", (e) => { throw new Error(`Cannot reach ${cfg.host}:${cfg.port}: ${e.message}`); });
s.on("timeout", () => { throw new Error("Connection timed out"); });

try {
  await startToolbox();
} catch (err) {
  if (String(err).includes("unable to connect successfully")) {
    console.error("Yugabyte ping failed — check server uptime, network, and credentials:", err.cause ?? err.message);
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: pool.Ping(ctx) fails during Initialize: Yugabyte/Postgres server down or unreachable at host:port, wrong user/password, database does not exist, TLS required but not configured, or firewall/network partition between the toolbox and the cluster.

Common situations: Database container not started or wrong Docker network; incorrect credentials in tools.yaml; connecting to a TLS-only cluster without sslmode settings; typo'd database name; Yugabyte node down while topology points only at it.

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
• unable to get Cloud SQL connection config: %w
• unable to connect successfully: %w
• unable to connect to Oracle successfully: %w

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