grpc: the connection is closing due to channel idleness

Error message

grpc: the connection is closing due to channel idleness

What it means

Thrown by buildLogger when audit.GetLoggerBuilder(loggerName) returns nil, meaning no audit logger factory has been registered for the name derived from the TypedConfig's TypeURL. gRPC's RBAC audit system requires loggers to be explicitly registered (e.g., stdout is registered by importing the stdout audit package). If the logger name is unrecognized and the config is not marked optional, this error fires.

Solutions

Ensure the audit logger package is imported (blank import _ 'google.golang.org/grpc/authz/audit/stdout') so its init() registers the builder.
Verify the logger name in the type_url exactly matches the Name returned by the logger's builder (e.g., 'stdout' for the standard stdout logger).
If the logger is not critical, set is_optional=true on the AuditLoggerConfig so buildLogger returns (nil, nil) instead of an error when the builder is missing.

Example fix

// before: server binary doesn't import the stdout audit package
import (
    "google.golang.org/grpc"
)

// after: blank-import the audit logger so its builder registers
import (
    _ "google.golang.org/grpc/authz/audit/stdout"
    "google.golang.org/grpc"
)

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the audit logger is registered before constructing the engine:
func ensureLoggerRegistered(name string) error {
    if audit.GetLoggerBuilder(name) == nil {
        return fmt.Errorf("audit logger %q is not registered; import its package", name)
    }
    return nil
}

// Or set is_optional=true to gracefully skip unregistered loggers:
loggerConfig.IsOptional = true

Prevention

Blank-import every audit logger package your xDS configs reference (e.g., _ "google.golang.org/grpc/authz/audit/stdout").
Set is_optional=true on audit logger configs so a missing builder degrades gracefully instead of failing.
Register custom audit loggers in an init() that is guaranteed to run before xDS processing.

When it happens

Trigger: An xDS RBAC policy references an audit logger whose name (from the type_url) does not match any logger registered via audit.RegisterLogger. For example, the control plane sends a logger name 'envoy.rbac.audit_loggers.stdout' but the gRPC server process did not import the grpc/authz/audit/stdout package that performs the registration in its init().

Common situations: The gRPC server binary does not import the stdout audit logger package, so no builder is registered for 'stdout'. A custom audit logger was developed but its RegisterLogger call was never executed (package not imported). A typo in the type_url produces a logger name that does not match any registration. The audit logger config is required (is_optional=false) when it should be optional.

Related errors

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

Appendix: source

Thrown at clientconn.go:77

const (
	// minimum time to give a connection to complete
	minConnectTimeout = 20 * time.Second
)

var (
	// ErrClientConnClosing indicates that the operation is illegal because
	// the ClientConn is closing.
	//
	// Deprecated: this error should not be relied upon by users; use the status
	// code of Canceled instead.
	ErrClientConnClosing = status.Error(codes.Canceled, "grpc: the client connection is closing")
	// errConnDrain indicates that the connection starts to be drained and does not accept any new RPCs.
	errConnDrain = errors.New("grpc: the connection is drained")
	// errConnClosing indicates that the connection is closing.
	errConnClosing = errors.New("grpc: the connection is closing")
	// errConnIdling indicates the connection is being closed as the channel
	// is moving to an idle mode due to inactivity.
	errConnIdling = errors.New("grpc: the connection is closing due to channel idleness")
	// invalidDefaultServiceConfigErrPrefix is used to prefix the json parsing error for the default
	// service config.
	invalidDefaultServiceConfigErrPrefix = "grpc: the provided default service config is invalid"
	// PickFirstBalancerName is the name of the pick_first balancer.
	PickFirstBalancerName = pickfirst.Name
)

// The following errors are returned from Dial and DialContext
var (
	// errNoTransportSecurity indicates that there is no transport security
	// being set for ClientConn. Users should either set one or explicitly
	// call WithInsecure DialOption to disable security.
	errNoTransportSecurity = errors.New("grpc: no transport security set (use grpc.WithTransportCredentials(insecure.NewCredentials()) explicitly or set credentials)")
	// errTransportCredsAndBundle indicates that creds bundle is used together
	// with other individual Transport Credentials.
	errTransportCredsAndBundle = errors.New("grpc: credentials.Bundle may not be used with individual TransportCredentials")
	// errNoTransportCredsInBundle indicated that the configured creds bundle
	// returned a transport credentials which was nil.

View on GitHub (pinned to 0c51461d27)