pinpoint-apm/pinpoint · error · IllegalArgumentException

matcher type must not be empty

Error message

matcher type must not be empty

What it means

Thrown by ParsedAnnotationKeyMatcher.toAnnotationKeyMatcher when a matcher entry in a YAML type-provider definition lacks a 'type' field (empty/null). The type selects which AnnotationKeyMatcher to build (exact/args/none), so it is mandatory.

Source

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

    public String getType() {
        return type;
    }

    public void setType(String type) {
        this.type = type;
    }

    public Integer getCode() {
        return code;
    }

    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. Set type to one of: exact, args, or none in the matcher entry
2. Remove the incomplete matcher entry if the default matching behavior is acceptable
3. Cross-check the yaml against a working plugin's type-provider definition
4. Reload the plugin after fixing and verify via agent startup logs

Example fix

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

matchers.forEach(m -> {
  if (m.getType() == null || m.getType().isEmpty()) throw new IllegalStateException("matcher missing type");
  if (!Set.of("exact","args","none").contains(m.getType().toLowerCase())) throw new IllegalStateException("bad matcher type: " + m.getType());
});

try { matcher = parsed.toAnnotationKeyMatcher(); } catch (IllegalArgumentException e) { log.error("bad annotationKeyMatcher in plugin yaml: {}", e.getMessage()); throw e; }

When it happens

Trigger: Loading a plugin yaml where annotationKeyMatcher is declared without type, e.g. only a code is given, or type: ''

Common situations: Partially written yaml definitions; misunderstanding that matcher entries require a type; copy-pasting only the code field from another matcher.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• annotationKey name must not be empty
• Unknown matcher type :
• 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/699b527995b5523e. Report an issue: GitHub.