{"id":"479128e05efd87ef","repo":"jackc/pgx","slug":"server-does-not-support-scram-sha-256","errorCode":null,"errorMessage":"server does not support SCRAM-SHA-256","messagePattern":"server does not support SCRAM-SHA-256","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pgconn/auth_scram.go","lineNumber":192,"sourceCode":"\tsalt                 []byte\n\titerations           int\n\n\tsaltedPassword []byte\n\tauthMessage    []byte\n}\n\nfunc newScramClient(serverAuthMechanisms []string, password string) (*scramClient, error) {\n\tsc := &scramClient{\n\t\tserverAuthMechanisms: serverAuthMechanisms,\n\t\tauthMechanism:        scramSHA256Name,\n\t}\n\n\t// Ensure the server supports SCRAM-SHA-256. SCRAM-SHA-256-PLUS is the\n\t// channel binding variant and is only advertised when the server supports\n\t// SSL. PostgreSQL always advertises the base SCRAM-SHA-256 mechanism\n\t// regardless of SSL.\n\tif !slices.Contains(sc.serverAuthMechanisms, scramSHA256Name) {\n\t\treturn nil, errors.New(\"server does not support SCRAM-SHA-256\")\n\t}\n\n\t// precis.OpaqueString is equivalent to SASLprep for password.\n\tvar err error\n\tsc.password, err = precis.OpaqueString.String(password)\n\tif err != nil {\n\t\t// PostgreSQL allows passwords invalid according to SCRAM / SASLprep.\n\t\tsc.password = password\n\t}\n\n\tbuf := make([]byte, clientNonceLen)\n\t_, err = rand.Read(buf)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tsc.clientNonce = make([]byte, base64.RawStdEncoding.EncodedLen(len(buf)))\n\tbase64.RawStdEncoding.Encode(sc.clientNonce, buf)\n","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/jackc/pgx/blob/ec1a0befd22592cffffdeeb0a50311b506372f4c/pgconn/auth_scram.go#L174-L210","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["On the server set password_encryption='scram-sha-256' and re-set the user's password so the stored hash is SCRAM.","Upgrade PostgreSQL to 10+ (14+ is the supported floor for pgx v5).","If the server legitimately only supports md5, that is incompatible with pgx's SCRAM-only path; use a server/role configured for SCRAM."],"exampleFix":"-- before: server has md5 passwords\nSHOW password_encryption; -- md5\n\n-- after\nALTER SYSTEM SET password_encryption = 'scram-sha-256';\nSELECT pg_reload_conf();\nALTER ROLE app PASSWORD 'secret'; -- re-hash with SCRAM","handlingStrategy":"validation","validationCode":"-- Verify server supports SCRAM before relying on it.\nSHOW password_encryption; -- expect scram-sha-256\nSELECT rolpassword FROM pg_authid WHERE rolname='app'; -- expect SCRAM-SHA-256 hash prefix","typeGuard":null,"tryCatchPattern":"if err := pgx.Connect(ctx, dsn); err != nil {\n    if strings.Contains(err.Error(), \"server does not support SCRAM-SHA-256\") {\n        // instruct ops to enable scram-sha-256; do not silently fall back to insecure auth\n        return fmt.Errorf(\"server must enable scram-sha-256 password encryption: %w\", err)\n    }\n}","preventionTips":["Standardize on password_encryption='scram-sha-256' across environments.","Re-set user passwords after changing password_encryption so hashes are SCRAM.","Keep PostgreSQL at the supported version floor (14+)."],"tags":["authentication","scram","server-config","postgresql"],"analyzedSha":"ec1a0befd22592cffffdeeb0a50311b506372f4c","analyzedAt":"2026-08-04T22:52:11.263Z","schemaVersion":2}