OAuth authentication required but no token provider configur

Error message

OAuth authentication required but no token provider configured

What it means

Returned by (*PgConn).oauthAuth when the server demands OAUTHBEARER SASL authentication (RFC 7628) but Config.OAuthTokenProvider is nil. pgx will not invent a token; the caller must supply a function returning a bearer token. Without it the SASL initial response cannot be constructed.

Source

Thrown at pgconn/auth_oauth.go:14

package pgconn

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"

	"github.com/jackc/pgx/v5/pgproto3"
)

func (c *PgConn) oauthAuth(ctx context.Context) error {
	if c.config.OAuthTokenProvider == nil {
		return errors.New("OAuth authentication required but no token provider configured")
	}

	token, err := c.config.OAuthTokenProvider(ctx)
	if err != nil {
		return fmt.Errorf("failed to obtain OAuth token: %w", err)
	}

	// https://www.rfc-editor.org/rfc/rfc7628.html#section-3.1
	initialResponse := []byte("n,,\x01auth=Bearer " + token + "\x01\x01")

	saslInitialResponse := &pgproto3.SASLInitialResponse{
		AuthMechanism: "OAUTHBEARER",
		Data:          initialResponse,
	}
	c.frontend.Send(saslInitialResponse)
	err = c.flushWithPotentialWriteReadDeadlock()
	if err != nil {
		return err

View on GitHub (pinned to ec1a0befd2)

Solutions

Set Config.OAuthTokenProvider (or the pgxpool equivalent) to a function returning a valid bearer token before calling Connect.
Confirm the server actually requires OAuth; if it should accept password/SCRAM, check the server's pg_hba.conf or cloud auth settings.
Ensure the token provider refreshes tokens and returns errors (not panics) when the token source is unavailable.

Example fix

// before
conn, err := pgx.Connect(ctx, "host=db user=app")

// after
conn, err := pgx.ConnectConfig(ctx, &pgx.ConnConfig{
    Host: "db",
    User: "app",
    OAuthTokenProvider: func(ctx context.Context) (string, error) {
        return tokenCache.Get(ctx) // returns fresh bearer token
    },
})

Defensive patterns

Strategy: validation

Validate before calling

// Before connecting, ensure a token provider is set when the server requires OAuth.
func validateOAuthConfig(cc *pgx.ConnConfig) error {
    // If you know the server uses OAUTHBEARER, the provider must be non-nil.
    if requiresOAuth(cc) && cc.OAuthTokenProvider == nil {
        return errors.New("server requires OAuth but OAuthTokenProvider is not set")
    }
    return nil
}

Try / catch

conn, err := pgx.ConnectConfig(ctx, cc)
if err != nil {
    if strings.Contains(err.Error(), "OAuth authentication required") {
        return fmt.Errorf("missing OAuth token provider: configure OAuthTokenProvider and retry: %w", err)
    }
    return err
}

Prevention

Centralize ConnConfig construction so OAuthTokenProvider is always wired for OAuth backends.
Make the token provider refresh tokens internally and surface errors cleanly.
Document which environments/hosts require OAuth in your service config.

When it happens

Trigger: Connecting to a server whose AuthenticationSASL message advertises 'OAUTHBEARER' while Config.OAuthTokenProvider == nil. Triggered via pgconn.ConnectConfig / pgx.Connect / pgxpool.New when the server is configured for OAuth (e.g. Postgres with an OAuth extension or a managed cloud proxy).

Common situations: Cloud DB offerings that require OAuth/Azure AD tokens; forgetting to wire OAuthTokenProvider after switching from password auth; token provider closure capturing an expired/empty cache.

Related errors

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