grpc/grpc-go · error

missing fallback credentials

Error message

missing fallback credentials

What it means

Returned by xds.NewClientCredentials when ClientOptions.FallbackCreds is nil. xDS client credentials require fallback TransportCredentials because the management server may not always provide security configuration (e.g., when the xds:// scheme is not used in the dial target). The fallback ensures the channel can still establish a connection in those cases.

Solutions

1. Set ClientOptions.FallbackCreds to a valid TransportCredentials instance, typically credentials.NewTLS(tlsConfig) or insecure.NewCredentials().
2. Use the same fallback you would have used without xDS credentials (your existing TLS config is usually correct).

Example fix

// before
creds, err := xds.NewClientCredentials(xds.ClientOptions{}) // error
// after
creds, err := xds.NewClientCredentials(xds.ClientOptions{
    FallbackCreds: credentials.NewTLS(&tls.Config{}),
})

if opts.FallbackCreds == nil {
    opts.FallbackCreds = credentials.NewTLS(&tls.Config{}) // or insecure.NewCredentials()
}
creds, err := xds.NewClientCredentials(opts)

When it happens

Trigger: Calling xds.NewClientCredentials(xds.ClientOptions{}) without setting FallbackCreds. The nil check rejects this immediately.

Common situations: Developers adopt xDS credentials but forget that a fallback is mandatory. Or they intend to use xDS-only security and pass nil, not realizing the design requires fallback for non-xDS targets.

Related errors

• ClientHandshake() is not supported for server credentials
• empty token_exchange_service_uri in options
• failed to build call credentials from bootstrap for
• failed to build credentials bundle from bootstrap for
• OutlierDetectionLoadBalancingConfig.base_ejection_time =

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/b1b92814a30a803a. Report an issue: GitHub.

Appendix: source

Thrown at credentials/xds/xds.go:50

	xdsinternal "google.golang.org/grpc/internal/credentials/xds"
	"google.golang.org/grpc/internal/grpcsync"
)

// ClientOptions contains parameters to configure a new client-side xDS
// credentials implementation.
type ClientOptions struct {
	// FallbackCreds specifies the fallback credentials to be used when either
	// the `xds` scheme is not used in the user's dial target or when the
	// management server does not return any security configuration. Attempts to
	// create client credentials without fallback credentials will fail.
	FallbackCreds credentials.TransportCredentials
}

// NewClientCredentials returns a new client-side transport credentials
// implementation which uses xDS APIs to fetch its security configuration.
func NewClientCredentials(opts ClientOptions) (credentials.TransportCredentials, error) {
	if opts.FallbackCreds == nil {
		return nil, errors.New("missing fallback credentials")
	}
	return &credsImpl{
		isClient: true,
		fallback: opts.FallbackCreds,
	}, nil
}

// ServerOptions contains parameters to configure a new server-side xDS
// credentials implementation.
type ServerOptions struct {
	// FallbackCreds specifies the fallback credentials to be used when the
	// management server does not return any security configuration. Attempts to
	// create server credentials without fallback credentials will fail.
	FallbackCreds credentials.TransportCredentials
}

// NewServerCredentials returns a new server-side transport credentials
// implementation which uses xDS APIs to fetch its security configuration.

View on GitHub (pinned to 0c51461d27)