jackc/pgx · error

server does not support SCRAM-SHA-256

Error message

server does not support SCRAM-SHA-256

What it means

Returned by newScramClient when the server's advertised SASL mechanisms do not contain 'SCRAM-SHA-256'. pgx only implements SCRAM-SHA-256 (+PLUS); if the server offers neither, password authentication cannot proceed. PostgreSQL 10+ advertises SCRAM-SHA-256 when password_encryption=scram-sha-256.

Source

Thrown at pgconn/auth_scram.go:192

	salt                 []byte
	iterations           int

	saltedPassword []byte
	authMessage    []byte
}

func newScramClient(serverAuthMechanisms []string, password string) (*scramClient, error) {
	sc := &scramClient{
		serverAuthMechanisms: serverAuthMechanisms,
		authMechanism:        scramSHA256Name,
	}

	// Ensure the server supports SCRAM-SHA-256. SCRAM-SHA-256-PLUS is the
	// channel binding variant and is only advertised when the server supports
	// SSL. PostgreSQL always advertises the base SCRAM-SHA-256 mechanism
	// regardless of SSL.
	if !slices.Contains(sc.serverAuthMechanisms, scramSHA256Name) {
		return nil, errors.New("server does not support SCRAM-SHA-256")
	}

	// precis.OpaqueString is equivalent to SASLprep for password.
	var err error
	sc.password, err = precis.OpaqueString.String(password)
	if err != nil {
		// PostgreSQL allows passwords invalid according to SCRAM / SASLprep.
		sc.password = password
	}

	buf := make([]byte, clientNonceLen)
	_, err = rand.Read(buf)
	if err != nil {
		return nil, err
	}
	sc.clientNonce = make([]byte, base64.RawStdEncoding.EncodedLen(len(buf)))
	base64.RawStdEncoding.Encode(sc.clientNonce, buf)

View on GitHub (pinned to ec1a0befd2)

Solutions

1. On the server set password_encryption='scram-sha-256' and re-set the user's password so the stored hash is SCRAM.
2. Upgrade PostgreSQL to 10+ (14+ is the supported floor for pgx v5).
3. If the server legitimately only supports md5, that is incompatible with pgx's SCRAM-only path; use a server/role configured for SCRAM.

Example fix

-- before: server has md5 passwords
SHOW password_encryption; -- md5

-- after
ALTER SYSTEM SET password_encryption = 'scram-sha-256';
SELECT pg_reload_conf();
ALTER ROLE app PASSWORD 'secret'; -- re-hash with SCRAM

-- Verify server supports SCRAM before relying on it.
SHOW password_encryption; -- expect scram-sha-256
SELECT rolpassword FROM pg_authid WHERE rolname='app'; -- expect SCRAM-SHA-256 hash prefix

if err := pgx.Connect(ctx, dsn); err != nil {
    if strings.Contains(err.Error(), "server does not support SCRAM-SHA-256") {
        // instruct ops to enable scram-sha-256; do not silently fall back to insecure auth
        return fmt.Errorf("server must enable scram-sha-256 password encryption: %w", err)
    }
}

When it happens

Trigger: Connecting with a password to a server that only offers md5 or cleartext auth (PostgreSQL < 10, or password_encryption=md5/smoke), or to a non-PostgreSQL server lacking SCRAM. Triggered during the SASL mechanism selection in scramAuth.

Common situations: Legacy PostgreSQL 9.x; server with password_encryption=md5; connecting through an older pooler that doesn't forward SCRAM; CockroachDB/other DB configured without SCRAM.

Related errors

• channel binding required but server does not support SCRAM-S
• channel binding required but channel binding data is not ava
• invalid SCRAM server-first-message received from server: did
• invalid SCRAM server-first-message received from server: did
• invalid SCRAM server-first-message received from server: did

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