jackc/pgx · error · perDialConnectError

%s: %w

Error message

%s: %w

What it means

A per-dial connection attempt failed and the error is wrapped with context (address, hostname, normalized timeout) before being aggregated. Multi-host configs try remaining fallbacks; if all fail the joined errors surface as a ConnectError. Connection-level failures like these are candidates for retry with backoff.

Solutions

1. Check the wrapped error for the root cause (refused, timeout, TLS, auth)
2. Verify the target address and port are correct and reachable
3. If multiple hosts are configured, ensure fallbacks are defined
4. Implement retry with backoff for transient network failures

When it happens

Trigger: Thrown at pgconn/pgconn.go:326 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/8fb07070cb222bb2. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/pgconn.go:326

	}

	return nil, allErrors
}

// connectOne makes one connection attempt to a single host.
func connectOne(ctx context.Context, config *Config, connectConfig *connectOneConfig,
	ignoreNotPreferredErr bool,
) (*PgConn, error) {
	pgConn := new(PgConn)
	pgConn.config = config
	pgConn.cleanupDone = make(chan struct{})
	pgConn.customData = make(map[string]any)

	var err error

	newPerDialConnectError := func(msg string, err error) *perDialConnectError {
		err = normalizeTimeoutError(ctx, err)
		e := &perDialConnectError{address: connectConfig.address, originalHostname: connectConfig.originalHostname, err: fmt.Errorf("%s: %w", msg, err)}
		return e
	}

	maxProtocolVersion, err := parseProtocolVersion(config.MaxProtocolVersion)
	if err != nil {
		return nil, newPerDialConnectError("invalid max_protocol_version", err)
	}
	minProtocolVersion, err := parseProtocolVersion(config.MinProtocolVersion)
	if err != nil {
		return nil, newPerDialConnectError("invalid min_protocol_version", err)
	}

	pgConn.conn, err = config.DialFunc(ctx, connectConfig.network, connectConfig.address)
	if err != nil {
		return nil, newPerDialConnectError("dial error", err)
	}

	if connectConfig.tlsConfig != nil {

View on GitHub (pinned to ec1a0befd2)