grpc/grpc-go · error

router: unexpected config override specified: %v

Error message

router: unexpected config override specified: %v

What it means

The gRPC router filter does not support per-route overrides. ParseFilterConfigOverride rejects any non-nil override message outright.

Source

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

	// 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
}

func (builder) IsTerminal() bool {
	return true
}

func (builder) BuildClientFilter(httpfilter.ClientFilterOptions) httpfilter.ClientFilter {
	return filter{}
}

func (builder) BuildServerFilter() httpfilter.ServerFilter {
	return filter{}
}

var _ httpfilter.ClientFilterBuilder = builder{}
var _ httpfilter.ServerFilterBuilder = builder{}

View on GitHub (pinned to 03255a9237)

Solutions

1. Remove the typed_per_filter_config entry for the router filter from the RouteConfiguration.
2. If you need per-route behavior, apply overrides to a filter that supports them (e.g. RBAC), not the router.

Example fix

// before (RDS route fragment)
// typed_per_filter_config:
//   envoy.filters.http.router:
//     - name: envoy.filters.http.router
//       typed_config: { ... }
//
// after: delete the router entry entirely

func ensureNoRouterOverride(route *routepb.Route) error {
	for name := range getTypedPerFilterConfig(route) {
		if name == "envoy.filters.http.router" {
			return fmt.Errorf("router filter must not have a per-route override")
		}
	}
	return nil
}

When it happens

Trigger: A RouteConfiguration typed_per_filter_config entry names the router filter with any override value.

Common situations: Copy-pasting Envoy config that sets a router override into a gRPC xDS setup; templating that adds per-route config to every filter uniformly.

Related errors

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

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