pinpoint-apm/pinpoint · error · IllegalArgumentException

Unknown code :

Error message

Unknown code : 

What it means

MatchingRule.getByCode throws IllegalArgumentException when the given int code does not match the code of any MatchingRule enum constant. The enum maps numeric rule codes (e.g. from serialized request data) to matching-rule instances, and unknown codes are rejected.

Solutions

1. Use only codes from the MatchingRule enum's defined constants (inspect MatchingRule.values() for valid code values).
2. Align frontend/backend versions so both share the same enum code set.
3. Catch IllegalArgumentException and fall back to a default matching rule.
4. Add the missing code as a new enum constant if the code is legitimately new.

Example fix

// before
MatchingRule rule = MatchingRule.getByCode(dto.getRuleCode());

// after
MatchingRule rule;
try {
    rule = MatchingRule.getByCode(dto.getRuleCode());
} catch (IllegalArgumentException e) {
    rule = MatchingRule.DEFAULT;
}

boolean valid = Arrays.stream(MatchingRule.values())
    .anyMatch(r -> r.code == code);

try {
    rule = MatchingRule.getByCode(code);
} catch (IllegalArgumentException e) {
    rule = MatchingRule.DEFAULT;
}

When it happens

Trigger: Calling MatchingRule.getByCode with a code outside the defined set — e.g. client sends ruleCode=7 while the enum only defines 0..n; deserializing old/new payloads whose codes don't match the deployed enum.

Common situations: Version skew between web frontend and backend after enum codes changed; hand-crafted API requests with guessed codes; stored dashboards persisting codes from a removed constant.

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 value :
• 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/a495bd8875baf3b9. 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:43

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

    public int getCode() {
        return code;
    }

    public String getValue() {
        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)