pinpoint-apm/pinpoint · error · IllegalStateException

Unknown matcher type :

Error message

Unknown matcher type : 

What it means

Thrown by ParsedAnnotationKeyMatcher.toAnnotationKeyMatcher when the matcher 'type' is non-empty but not one of the supported values: exact, args, or none. The loader cannot map the unknown type to an AnnotationKeyMatcher and aborts plugin metadata loading.

Source

Thrown at agent-module/plugins-loader/src/main/java/com/navercorp/pinpoint/loader/plugins/trace/yaml/ParsedAnnotationKeyMatcher.java:61

    }

    public void setCode(Integer code) {
        this.code = code;
    }

    AnnotationKeyMatcher toAnnotationKeyMatcher() {
        if (StringUtils.isEmpty(type)) {
            throw new IllegalArgumentException("matcher type must not be empty");
        }
        if (type.equalsIgnoreCase("exact")) {
            Objects.requireNonNull(code, "code must not be null for matcher type 'exact'");
            return AnnotationKeyMatchers.exact(code);
        } else if (type.equalsIgnoreCase("args")) {
            return AnnotationKeyMatchers.ARGS_MATCHER;
        } else if (type.equalsIgnoreCase("none")) {
            return AnnotationKeyMatchers.NOTHING_MATCHER;
        }
        throw new IllegalStateException("Unknown matcher type : " + type);
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Change type to one of the supported values: exact, args, or none
2. Fix typos in the type value (matching is case-insensitive, so 'EXACT' is fine)
3. If custom matching is required, implement it in the plugin code rather than via yaml matcher type
4. Compare with existing plugin yamls in the pinpoint repository for valid examples

Example fix

// before (plugin yaml)
annotationKeyMatcher:
  - code: 900
    type: prefix
// after
annotationKeyMatcher:
  - code: 900
    type: exact

String t = matcher.getType();
if (t != null && !Set.of("exact","args","none").contains(t.toLowerCase())) {
  throw new IllegalStateException("unsupported matcher type '" + t + "'; use exact|args|none");
}

try { matcher = parsed.toAnnotationKeyMatcher(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Unknown matcher type")) { log.error("supported types: exact, args, none"); } throw e; }

When it happens

Trigger: YAML type-provider definition declares annotationKeyMatcher with type like 'regex', 'prefix', 'startsWith', or a misspelled 'excat' — anything not matching exact/args/none case-insensitively.

Common situations: Authors assuming matcher types from other libraries (regex/prefix) are supported; typos in 'exact'/'args'/'none'; outdated documentation or copied configs from incompatible plugin versions.

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

• annotationKey name must not be empty
• matcher type must not be empty
• service type name must not be empty
• Invalid type provider definition :
• Error parsing yml :

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