What causes "Unknown value : " in pinpoint-apm/pinpoint?

Use one of GroupingRule.values() values (inspect the enum for the exact accepted strings, comparison is case-insensitive).

pinpoint-apm/pinpoint · error · IllegalArgumentException

Unknown value :

Error message

Unknown value :

What it means

GroupingRule.getByValue throws IllegalArgumentException when the given string does not case-insensitively match the value of any GroupingRule enum constant. The enum maps request-supplied grouping values to internal grouping strategies, so only known values are accepted.

Solutions

Use one of GroupingRule.values() values (inspect the enum for the exact accepted strings, comparison is case-insensitive).
Validate/normalize the incoming value against the enum before calling getByValue.
Catch IllegalArgumentException and fall back to a default GroupingRule.
If a new grouping is genuinely needed, add a new enum constant with the corresponding value.

Example fix

// before
GroupingRule rule = GroupingRule.getByValue(request.getParameter("grouping"));

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

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

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

Prevention

Derive allowed grouping values in the frontend from the same enum source.
Document valid values in the API and validate at the controller layer.
Prefer an Optional-returning lookup when adding new enum APIs.

When it happens

Trigger: Calling GroupingRule.getByValue with a value not in the enum's values() — e.g. a typo, a request query parameter carrying an unsupported grouping value, or a value from a different Pinpoint version.

Common situations: Frontend sending a grouping value not yet supported by the backend; API consumers copying values from docs of another version; manual edits to saved dashboard definitions referencing removed grouping rules.

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

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

Appendix: source

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

        this.value = Objects.requireNonNull(value, "value");
    }

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

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

View on GitHub (pinned to 744c3d3075)