grpc/grpc-go · error
empty prefix is not allowed in StringMatcher
Error message
empty prefix is not allowed in StringMatcher
What it means
Returned by StringMatcherFromProto (string_matcher.go:107-108) for the Prefix match variant when the prefix string is empty. An empty prefix would match every string and is considered a configuration mistake; callers wanting that behavior should use an explicit exact-empty or present matcher instead.
Source
Thrown at internal/xds/matcher/string_matcher.go:108
return s
}
// StringMatcherFromProto is a helper function to create a StringMatcher from
// the corresponding StringMatcher proto.
//
// Returns a non-nil error if matcherProto is invalid.
func StringMatcherFromProto(matcherProto *v3matcherpb.StringMatcher) (StringMatcher, error) {
if matcherProto == nil {
return StringMatcher{}, errors.New("input StringMatcher proto is nil")
}
matcher := StringMatcher{ignoreCase: matcherProto.GetIgnoreCase()}
switch mt := matcherProto.GetMatchPattern().(type) {
case *v3matcherpb.StringMatcher_Exact:
matcher.exactMatch = newStrPtr(&mt.Exact, matcher.ignoreCase)
case *v3matcherpb.StringMatcher_Prefix:
if matcherProto.GetPrefix() == "" {
return StringMatcher{}, errors.New("empty prefix is not allowed in StringMatcher")
}
matcher.prefixMatch = newStrPtr(&mt.Prefix, matcher.ignoreCase)
case *v3matcherpb.StringMatcher_Suffix:
if matcherProto.GetSuffix() == "" {
return StringMatcher{}, errors.New("empty suffix is not allowed in StringMatcher")
}
matcher.suffixMatch = newStrPtr(&mt.Suffix, matcher.ignoreCase)
case *v3matcherpb.StringMatcher_SafeRegex:
regex := matcherProto.GetSafeRegex().GetRegex()
re, err := CompileSafeRegex(regex)
if err != nil {
return StringMatcher{}, fmt.Errorf("safe_regex matcher %q is invalid", regex)
}
matcher = NewRegexStringMatcher(re)
case *v3matcherpb.StringMatcher_Contains:
if matcherProto.GetContains() == "" {
return StringMatcher{}, errors.New("empty contains is not allowed in StringMatcher")
}View on GitHub (pinned to 03255a9237)
Solutions
- Provide a non-empty prefix value in the StringMatcher config.
- If the intent is 'match everything', drop the matcher entirely or use an always-allow permission.
- Sanitize generated matchers: reject/omit prefix matchers with empty values before sending to xDS.
Example fix
// before: { "prefix": "" }
// after: { "prefix": "/api/v1/" } // or remove the matcher if all-match is intended Defensive patterns
Strategy: validation
Validate before calling
func validPrefixStringMatcher(m *v3matcherpb.StringMatcher) error {
if m.GetPrefix() == "" {
return errors.New("prefix matcher must have a non-empty prefix")
}
return nil
} Prevention
- Reject empty prefix values when generating matchers.
- Prefer exact matchers when the intent is a precise value, not a wildcard.
- Add a config-lint step for RBAC/route matchers before publishing.
When it happens
Trigger: A StringMatcher proto whose match pattern is StringMatcher_Prefix with Prefix="". The type switch detects the Prefix case, checks matcherProto.GetPrefix()=="", and rejects it.
Common situations: Control-plane templating that emits prefix matchers with a variable that resolved to empty; an RBAC/route rule intended to match all but authored as an empty prefix.
Related errors
- empty suffix is not allowed in StringMatcher
- empty contains is not allowed in StringMatcher
- input StringMatcher proto is nil
- unknown header matcher type
- filter missing name field
AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07).
Data as JSON: /api/errors/b69462e32b2640e6.
Report an issue: GitHub.