grpc/grpc-go · error

router: nil configuration message provided

Error message

router: nil configuration message provided

What it means

The router filter's ParseFilterConfig rejects a nil config message. Although the router ignores the config body (it only verifies the type), it still requires a non-nil typed_config so the filter entry is well-formed.

Source

Thrown at internal/xds/httpfilter/router/router.go:55

	httpfilter.Register(builder{})
}

// IsRouterFilter returns true iff b is a Router filter builder.
func IsRouterFilter(b httpfilter.Builder) bool {
	_, ok := b.(builder)
	return ok
}

type builder struct {
}

func (builder) TypeURLs() []string { return []string{TypeURL} }

func (builder) ParseFilterConfig(cfg proto.Message) (httpfilter.FilterConfig, error) {
	// The gRPC router filter does not currently use any fields from the
	// config.  Verify type only.
	if cfg == nil {
		return nil, fmt.Errorf("router: nil configuration message provided")
	}
	m, ok := cfg.(*anypb.Any)
	if !ok {
		return nil, fmt.Errorf("router: error parsing config %v: unknown type %T", cfg, cfg)
	}
	msg := new(pb.Router)
	if err := m.UnmarshalTo(msg); err != nil {
		return nil, fmt.Errorf("router: error parsing config %v: %v", cfg, err)
	}
	return config{}, nil
}

func (builder) ParseFilterConfigOverride(override proto.Message) (httpfilter.FilterConfig, error) {
	if override != nil {
		return nil, fmt.Errorf("router: unexpected config override specified: %v", override)
	}
	return config{}, nil
}

View on GitHub (pinned to 03255a9237)

Solutions

1. Ensure the router filter entry carries a typed_config Any wrapping envoy.extensions.filters.http.router.v3.Router.
2. Validate LDS resources on the control plane before serving.

func ensureRouterFilterConfigPresent(filters []*hcmpb.HttpFilter) error {
	for _, f := range filters {
		if isRouterFilter(f) && f.GetTypedConfig() == nil {
			return fmt.Errorf("router filter %q has nil typed_config", f.GetName())
		}
	}
	return nil
}

When it happens

Trigger: An LDS HTTP filter chain entry references the router filter but supplies no typed_config (nil).

Common situations: Control plane emitting a router filter entry without a body; minimal/templated xDS resources missing the router config; custom xDS server bug.

Related errors

• router: unexpected config override specified: %v
• missing fallback credentials
• rbac: permission header matcher for %v is :scheme or starts
• rbac: nil configuration message provided
• router: error parsing config %v: unknown type %T

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/9bc7a35186caa90d. Report an issue: GitHub.