pinpoint-apm/pinpoint · error · IllegalArgumentException

Unknown value :

Error message

Unknown value : 

What it means

MatchingRule.getByValue throws IllegalArgumentException when the given string does not case-insensitively equal the value of any MatchingRule enum constant. It is the string-based lookup counterpart of getByCode and accepts only known enum values.

Solutions

1. Use a value that exactly matches one of MatchingRule.values()' value fields (case-insensitive).
2. Validate the input against the enum before lookup, or expose the valid values in API docs.
3. Catch IllegalArgumentException and fall back to a default MatchingRule.
4. If a new matching semantic is needed, add a new enum constant.

Example fix

// before
MatchingRule rule = MatchingRule.getByValue(request.getParameter("matchingRule"));

// after
String v = request.getParameter("matchingRule");
MatchingRule rule;
try {
    rule = MatchingRule.getByValue(v);
} catch (IllegalArgumentException e) {
    rule = MatchingRule.DEFAULT;
}

boolean valid = Arrays.stream(MatchingRule.values())
    .anyMatch(r -> r.value.equalsIgnoreCase(candidate));

try {
    rule = MatchingRule.getByValue(value);
} catch (IllegalArgumentException e) {
    rule = MatchingRule.DEFAULT;
}

When it happens

Trigger: Calling MatchingRule.getByValue with a misspelled or unsupported rule value string, or one from a mismatched API version — typically a request parameter specifying how metric tags should be matched.

Common situations: Typo in query parameter values like 'exact'/'contain' variants; frontend/backend version skew; copying example values from outdated documentation.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown code :
• Unknown value :
• agentIds size exceeds max limit. size: <agentIds.size()>…
• args size not equal
• class name must not be null

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/2335a1c401b349f3. Report an issue: GitHub.

Appendix: source

Thrown at metric-module/metric/src/main/java/com/navercorp/pinpoint/metric/web/model/basic/metric/group/MatchingRule.java:52

        return value;
    }

    public static MatchingRule getByCode(int code) {
        for (MatchingRule matchingRule : MatchingRule.values()) {
            if (matchingRule.code == code) {
                return matchingRule;
            }
        }
        throw new IllegalArgumentException("Unknown code : " + code);
    }

    public static MatchingRule getByValue(String value) {
        for (MatchingRule matchingRule : MatchingRule.values()) {
            if (matchingRule.value.equalsIgnoreCase(value)) {
                return matchingRule;
            }
        }
        throw new IllegalArgumentException("Unknown value : " + value);
    }
}

View on GitHub (pinned to 744c3d3075)