jackc/pgx · error

authentication method requirement

Error message

authentication method requirement %q failed: %s

What it means

The require_auth policy was violated: the server's chosen (or absent) authentication method is not in the allowed set. The reason string states whether the server skipped authentication entirely or requested a disallowed method. Mirrors libpq's require_auth diagnostics.

Solutions

1. Align the require_auth list with the server's actual auth method
2. If the server did not authenticate, fix pg_hba.conf to require auth
3. Remove or adjust the require_auth setting in the connection string
4. Check for typos in method names like scram-sha-256

When it happens

Trigger: Thrown at pgconn/require_auth.go:64 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/6518c5f6c80848d0. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/require_auth.go:64

func (ra requireAuth) allows(m authMethod) bool {
	return ra.allowed&(1<<m) != 0
}

// check returns an error if method m is not permitted by the policy. The reason is phrased to
// follow libpq's "authentication method requirement \"%s\" failed: %s" form so users migrating
// from libpq see familiar diagnostics.
func (ra requireAuth) check(m authMethod) error {
	if ra.allows(m) {
		return nil
	}
	var reason string
	if m == authMethodNone {
		reason = "server did not complete authentication"
	} else {
		reason = fmt.Sprintf("server requested %s authentication", authMethodNames[m])
	}
	return fmt.Errorf("authentication method requirement %q failed: %s", ra.raw, reason)
}

// parseRequireAuth parses the require_auth connection parameter with libpq-compatible semantics:
// a comma-separated list of method names, optionally each prefixed with "!" to negate. Negated and
// non-negated entries cannot be mixed; duplicate entries are rejected. An empty string yields a
// permissive policy (all methods allowed, no authentication required).
func parseRequireAuth(s string) (requireAuth, error) {
	ra := requireAuth{raw: s}

	if s == "" {
		ra.allowed = 1<<authMethodCount - 1
		return ra, nil
	}

	first := true
	negated := false
	for part := range strings.SplitSeq(s, ",") {
		method := strings.TrimSpace(part)

View on GitHub (pinned to ec1a0befd2)