pinpoint-apm/pinpoint · error · IllegalArgumentException

Unknown CheckerCategory :

Error message

Unknown CheckerCategory : 

What it means

CheckerCategory.getValue performs a case-insensitive lookup of an alarm checker category by name over the CHECKER_CATEGORIES array. If no category name equals the given value, it throws IllegalArgumentException. This protects callers from resolving an unknown string into a CheckerCategory enum-like constant.

Solutions

1. Check the exact category name via CheckerCategory.getNames() and correct the input string
2. Validate user-supplied checker names against getNames() before calling getValue
3. If a category was removed/renamed in a Pinpoint upgrade, update alarm rule configs to the new name

Example fix

// before
CheckerCategory category = CheckerCategory.getValue("HEAP_USEAGE");
// after
List<String> valid = CheckerCategory.getNames();
if (!valid.contains(checkerName)) { throw new IllegalArgumentException(checkerName + " not in " + valid); }
CheckerCategory category = CheckerCategory.getValue(checkerName);

boolean isValidChecker(String name) {
    return name != null && CheckerCategory.getNames().stream().anyMatch(n -> n.equalsIgnoreCase(name));
}
// call CheckerCategory.getValue only if isValidChecker(name)

CheckerCategory tryGetChecker(String name) {
    for (String n : CheckerCategory.getNames()) {
        if (n.equalsIgnoreCase(name)) return CheckerCategory.getValue(n);
    }
    return null;
}

try {
    CheckerCategory c = CheckerCategory.getValue(name);
} catch (IllegalArgumentException e) {
    logger.warn("Invalid checker category: {}", name);
    // reject config or fall back to default category
}

When it happens

Trigger: Calling CheckerCategory.getValue with a string that is not one of the registered checker category names (typo, wrong case is tolerated, but e.g. 'HEAP_USAGE' vs 'HEAP_USAGE_RATE', or an empty/null string).

Common situations: Users typing an alarm rule checker name incorrectly in webhook/alarm configuration JSON, upgrading Pinpoint where a checker name was renamed, or building alarm rules programmatically from user input.

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

• agentStartTimeIndex not found
• application serviceType not found. code:, name:
• Cannot add an existing column family :
• ${fieldName}
• filter resolve fail:

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

Appendix: source

Thrown at web/src/main/java/com/navercorp/pinpoint/web/alarm/CheckerCategory.java:70

    
    JVM_CPU_USAGE_RATE("JVM CPU USAGE RATE", DataCollectorCategory.JVM_CPU_USAGE_RATE),

    SYSTEM_CPU_USAGE_RATE("SYSTEM CPU USAGE RATE", DataCollectorCategory.SYSTEM_CPU_USAGE_RATE),

    DATASOURCE_CONNECTION_USAGE_RATE("DATASOURCE CONNECTION USAGE RATE", DataCollectorCategory.DATA_SOURCE_STAT),
    DEADLOCK_OCCURRENCE("DEADLOCK OCCURRENCE", DataCollectorCategory.AGENT_EVENT),
    FILE_DESCRIPTOR_COUNT("FILE DESCRIPTOR COUNT", DataCollectorCategory.FILE_DESCRIPTOR);

    private static final CheckerCategory[] CHECKER_CATEGORIES = CheckerCategory.values();

    
    public static CheckerCategory getValue(String value) {
        for (CheckerCategory category : CHECKER_CATEGORIES) {
            if (category.getName().equalsIgnoreCase(value)) {
                return category;
            }
        }
        throw new IllegalArgumentException("Unknown CheckerCategory : " + value);
    }

    public static List<String> getNames() {

        final List<String> names = new ArrayList<>(CHECKER_CATEGORIES.length);
        for (CheckerCategory category : CHECKER_CATEGORIES) {
            names.add(category.getName());
        }
        
        return names;
    }

    private final String name;
    private final DataCollectorCategory dataCollectorCategory;

    CheckerCategory(String name, DataCollectorCategory dataCollectorCategory) {
        this.name = name;
        this.dataCollectorCategory = dataCollectorCategory;

View on GitHub (pinned to 744c3d3075)