jackc/pgx · error

expected AuthenticationSASLFinal message but received…

Error message

expected AuthenticationSASLFinal message but received unexpected message %T

What it means

During SCRAM authentication the client expected an AuthenticationSASLFinal message (the server-final-message) but received a different backend message type. The SASL exchange is out of sequence and authentication fails.

Solutions

1. Inspect the unexpected message type (%T) reported in the error
2. Confirm the server implements SCRAM-SHA-256 correctly
3. Check for protocol interference from proxies or poolers
4. Retry the connection to rule out transient corruption

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

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

Appendix: source

Thrown at pgconn/auth_scram.go:141

		return nil, ErrorResponseToPgError(m)
	}

	return nil, fmt.Errorf("expected AuthenticationSASLContinue message but received unexpected message %T", msg)
}

func (c *PgConn) rxSASLFinal() (*pgproto3.AuthenticationSASLFinal, error) {
	msg, err := c.receiveMessage()
	if err != nil {
		return nil, err
	}
	switch m := msg.(type) {
	case *pgproto3.AuthenticationSASLFinal:
		return m, nil
	case *pgproto3.ErrorResponse:
		return nil, ErrorResponseToPgError(m)
	}

	return nil, fmt.Errorf("expected AuthenticationSASLFinal message but received unexpected message %T", msg)
}

type scramClient struct {
	serverAuthMechanisms []string
	password             string
	clientNonce          []byte

	// authMechanism is the selected SASL mechanism for the client. Must be
	// either SCRAM-SHA-256 (default) or SCRAM-SHA-256-PLUS.
	//
	// Upgraded to SCRAM-SHA-256-PLUS during authentication when channel binding
	// is not disabled, channel binding data is available (TLS connection with
	// an obtainable server certificate hash) and the server advertises
	// SCRAM-SHA-256-PLUS.
	authMechanism string

	// hasTLS indicates whether the connection is using TLS. This is
	// needed because the GS2 header must distinguish between a client that

View on GitHub (pinned to ec1a0befd2)