pinpoint-apm/pinpoint · error · IllegalArgumentException

annotationKey name must not be empty

Error message

annotationKey name must not be empty

What it means

Thrown by ParsedAnnotationKey.toAnnotationKey when the YAML type-provider definition has an annotationKey entry whose 'name' field is empty or missing (the 'code' being already null-checked). A valid AnnotationKey requires both a numeric code and a non-empty name.

Source

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

    }

    public void setName(String name) {
        this.name = name;
    }

    public ParsedAnnotationKeyProperty getProperty() {
        return property;
    }

    public void setProperty(ParsedAnnotationKeyProperty property) {
        this.property = property;
    }

    AnnotationKey toAnnotationKey() {
        Objects.requireNonNull(code, "code");

        if (StringUtils.isEmpty(name)) {
            throw new IllegalArgumentException("annotationKey name must not be empty");
        }
        AnnotationKeyBuilder builder = new AnnotationKeyBuilder(code, name);
        if (property != null) {
            builder.viewInRecordSet(property.isViewInRecordSet());
        }
        return builder.build();
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Add a non-empty name to the annotationKey entry in the plugin's yaml file
2. Remove the incomplete annotationKey entry if it is not needed
3. Validate the yaml against existing working plugin definitions as a reference
4. Check the exception's originating yaml file in the plugin jar that failed to load

Example fix

// before (plugin yaml)
annotationKey:
  - code: 900
    # name missing
// after
annotationKey:
  - code: 900
    name: my.plugin.key

// pre-validate plugin yaml before packaging
annotationKeys.forEach(k -> {
  if (k.getCode() == null) throw new IllegalStateException("annotationKey missing code");
  if (k.getName() == null || k.getName().isEmpty()) throw new IllegalStateException("annotationKey missing name");
});

try { AnnotationKey key = parsed.toAnnotationKey(); } catch (IllegalArgumentException e) { log.error("bad annotationKey in plugin yaml: {}", e.getMessage()); throw e; }

When it happens

Trigger: Loading a plugin's yaml type provider where an annotationKey declares a code but no name, or name: '' (empty string).

Common situations: Hand-edited plugin annotationKey yaml with a forgotten name field; copy-pasted entry with only code; template yaml left partially filled in.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• matcher type 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/79a5443a7eac1895. Report an issue: GitHub.