jackc/pgx · error · ConnectError

hostname resolving error

Error message

hostname resolving error: %w

What it means

All host lookup attempts in the connection configuration failed; no connectable addresses were produced. This wraps the joined DNS/lookup errors for every host in the multi-host configuration. Named lookups, unlike subsequent connection errors, can be worth retrying since DNS can be transient.

Solutions

1. Check hostname spelling in the connection string
2. Verify DNS resolution works (dig or nslookup)
3. If using a custom LookupFunc, verify its behavior
4. Retry with backoff — DNS failures are often transient

When it happens

Trigger: Thrown at pgconn/pgconn.go:158 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/c44b05f77f1e2322. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/pgconn.go:158

// If config.Fallbacks are present they will sequentially be tried in case of error establishing network connection. An
// authentication error will terminate the chain of attempts (like libpq:
// https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS) and be returned as the error.
func ConnectConfig(ctx context.Context, config *Config) (*PgConn, error) {
	// Default values are set in ParseConfig. Enforce initial creation by ParseConfig rather than setting defaults from
	// zero values.
	if !config.createdByParseConfig {
		panic("config must be created by ParseConfig")
	}

	var allErrors []error

	connectConfigs, errs := buildConnectOneConfigs(ctx, config)
	if len(errs) > 0 {
		allErrors = append(allErrors, errs...)
	}

	if len(connectConfigs) == 0 {
		return nil, &ConnectError{Config: config, err: fmt.Errorf("hostname resolving error: %w", errors.Join(allErrors...))}
	}

	pgConn, errs := connectPreferred(ctx, config, connectConfigs)
	if len(errs) > 0 {
		allErrors = append(allErrors, errs...)
		return nil, &ConnectError{Config: config, err: errors.Join(allErrors...)}
	}

	if config.AfterConnect != nil {
		err := config.AfterConnect(ctx, pgConn)
		if err != nil {
			pgConn.conn.Close()
			return nil, &ConnectError{Config: config, err: fmt.Errorf("AfterConnect error: %w", err)}
		}
	}

	return pgConn, nil
}

View on GitHub (pinned to ec1a0befd2)