rls: GrpcKeyBuilder in RouteLookupConfig contains repeated…

Error message

rls: GrpcKeyBuilder in RouteLookupConfig contains repeated Name field {%+v}

What it means

The RLS BuilderMap is keyed by request path ("/service/method" or "/service/"). Two GrpcKeyBuilder Names that resolve to the same path are ambiguous, so MakeBuilderMap rejects the second one (builder.go:96-99). This keeps a deterministic one-builder-per-path mapping so RLS keys are unambiguous.

Solutions

List every path your GrpcKeyBuilders produce and remove the duplicate so each path appears exactly once.
If you need service-wide plus method-specific behavior, use distinct services or methods, or consolidate into a single builder with the desired header matchers.

Example fix

// before
kb1.Names = []*rlspb.Name{{Service: "S", Method: "M"}}
kb2.Names = []*rlspb.Name{{Service: "S", Method: "M"}} // duplicate path /S/M
// after
kb2.Names = []*rlspb.Name{{Service: "S", Method: "Other"}}

Defensive patterns

Strategy: validation

Validate before calling

func validateNoDuplicatePaths(cfg *rlspb.RouteLookupConfig) error {
	paths := map[string]bool{}
	for _, kb := range cfg.GetGrpcKeybuilders() {
		for _, n := range kb.GetNames() {
			p := "/" + n.GetService() + "/" + n.GetMethod()
			if paths[p] { return fmt.Errorf("duplicate path %q", p) }
			paths[p] = true
		}
	}
	return nil
}

Prevention

Maintain the set of paths your builders cover; reject duplicates during config authoring.
Avoid mixing service-wide and method-specific builders for the same service.
Test with keys.MakeBuilderMap to surface overlaps.

When it happens

Trigger: Two Names across one or more GrpcKeyBuilders produce the same path string. E.g., one builder declares {Service:"S", Method:"M"} and another declares {Service:"S"} (service-wide); both expand to overlapping paths, or two entries expand to the identical "/S/M".

Common situations: Adding a new key builder without checking the existing paths; merging configs from two teams; declaring both a service-wide and a method-specific builder for the same service.

Related errors

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

Appendix: source

Thrown at balancer/rls/internal/keys/builder.go:98

		}

		// Store the builder created above in the BuilderMap based on the value
		// of the `Names` field, which wraps incoming request's service and
		// method. Also, ensure that there are no repeated `Names` field.
		names := kb.GetNames()
		if len(names) == 0 {
			return nil, fmt.Errorf("rls: GrpcKeyBuilder in RouteLookupConfig does not contain any Name {%+v}", kbs)
		}
		for _, name := range names {
			if name.GetService() == "" {
				return nil, fmt.Errorf("rls: GrpcKeyBuilder in RouteLookupConfig contains a Name field with no Service {%+v}", kbs)
			}
			if strings.Contains(name.GetMethod(), `/`) {
				return nil, fmt.Errorf("rls: GrpcKeyBuilder in RouteLookupConfig contains a method with a slash {%+v}", kbs)
			}
			path := "/" + name.GetService() + "/" + name.GetMethod()
			if _, ok := bm[path]; ok {
				return nil, fmt.Errorf("rls: GrpcKeyBuilder in RouteLookupConfig contains repeated Name field {%+v}", kbs)
			}
			bm[path] = b
		}
	}
	return bm, nil
}

// KeyMap represents the RLS keys to be used for a request.
type KeyMap struct {
	// Map is the representation of an RLS key as a Go map. This is used when
	// an actual RLS request is to be sent out on the wire, since the
	// RouteLookupRequest proto expects a Go map.
	Map map[string]string
	// Str is the representation of an RLS key as a string, sorted by keys.
	// Since the RLS keys are part of the cache key in the request cache
	// maintained by the RLS balancer, and Go maps cannot be used as keys for
	// Go maps (the cache is implemented as a map), we need a stringified
	// version of it.

View on GitHub (pinned to 0c51461d27)