grpc/grpc-go · error
router: unexpected override configuration specified: %v
Error message
router: unexpected override configuration specified: %v
What it means
BuildClientInterceptor also rejects overrides: the router filter does not accept a per-route override at interceptor-build time (mirroring ParseFilterConfigOverride). Passing a non-nil override is an error.
Source
Thrown at internal/xds/httpfilter/router/router.go:99
}
func (builder) BuildServerFilter() httpfilter.ServerFilter {
return filter{}
}
var _ httpfilter.ClientFilterBuilder = builder{}
var _ httpfilter.ServerFilterBuilder = builder{}
type filter struct{}
func (filter) Close() {}
func (filter) BuildClientInterceptor(cfg, override httpfilter.FilterConfig) (httpfilter.ClientInterceptor, error) {
if _, ok := cfg.(config); !ok {
return nil, fmt.Errorf("router: incorrect config type provided (%T): %v", cfg, cfg)
}
if override != nil {
return nil, fmt.Errorf("router: unexpected override configuration specified: %v", override)
}
// The gRPC router is implemented within the xds resolver's config
// selector, not as a separate plugin. So we return a nil HTTPFilter,
// which will not be invoked.
return nil, nil
}
func (filter) BuildServerInterceptor(cfg, override httpfilter.FilterConfig) (iresolver.ServerInterceptor, error) {
if _, ok := cfg.(config); !ok {
return nil, fmt.Errorf("router: incorrect config type provided (%T): %v", cfg, cfg)
}
if override != nil {
return nil, fmt.Errorf("router: unexpected override configuration specified: %v", override)
}
// The gRPC router is currently unimplemented on the server side. So we
// return a nil HTTPFilter, which will not be invoked.
return nil, nil
}View on GitHub (pinned to 03255a9237)
Solutions
- Do not pass an override for the router filter when constructing its interceptor.
- Ensure the resolver's config selector drops router overrides (they are rejected at parse time too).
Defensive patterns
Strategy: validation
Validate before calling
// In custom resolver wiring, never forward an override to the router filter.
func dropRouterOverride(name string, override httpfilter.FilterConfig) httpfilter.FilterConfig {
if name == "envoy.filters.http.router" {
return nil
}
return override
} Prevention
- Filter out overrides for the router filter in the config selector.
- Reject router overrides at parse time (ParseFilterConfigOverride already does).
When it happens
Trigger: BuildClientInterceptor is invoked with a non-nil override for the router filter.
Common situations: Internal wiring that forwards overrides to all filters uniformly; a per-route config that should have been filtered out for the router.
Related errors
- rbac: incorrect override config type provided (%T): %v
- router: unexpected config override specified: %v
- router: incorrect config type provided (%T): %v
- rbac: error parsing override config %v: unknown type %T
- rbac: error parsing override config %v: %v
AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07).
Data as JSON: /api/errors/72f58a6190cacdb2.
Report an issue: GitHub.