jackc/pgx · error

server refused TLS connection

Error message

server refused TLS connection

What it means

During connection establishment pgx sent the SSLRequest startup packet, but the server answered with a byte other than 'S', meaning TLS is not enabled (or not supported) on that endpoint. The server's TLS configuration is the faulty input; this fires when sslmode demanded TLS the server cannot provide.

Solutions

1. Enable TLS on the PostgreSQL server (ssl=on with a valid certificate)
2. Relax sslmode to 'prefer' or 'disable' if encrypted connections are not required
3. Check that a TLS-terminating proxy in front of PostgreSQL is correctly configured

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

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

Appendix: source

Thrown at pgconn/pgconn.go:553

			pgConn.conn.Close()
			return nil, newPerDialConnectError("received unexpected message", err)
		}
	}
}

func startTLS(conn net.Conn, tlsConfig *tls.Config) (net.Conn, error) {
	err := binary.Write(conn, binary.BigEndian, []int32{8, 80877103})
	if err != nil {
		return nil, err
	}

	response := make([]byte, 1)
	if _, err = io.ReadFull(conn, response); err != nil {
		return nil, err
	}

	if response[0] != 'S' {
		return nil, errors.New("server refused TLS connection")
	}

	return tls.Client(conn, tlsConfig), nil
}

func (pgConn *PgConn) txPasswordMessage(password string) (err error) {
	pgConn.frontend.Send(&pgproto3.PasswordMessage{Password: password})
	return pgConn.flushWithPotentialWriteReadDeadlock()
}

func hexMD5(s string) string {
	hash := md5.New()
	io.WriteString(hash, s)
	return hex.EncodeToString(hash.Sum(nil))
}

func (pgConn *PgConn) signalMessage() chan struct{} {
	if pgConn.bufferingReceive {

View on GitHub (pinned to ec1a0befd2)