pinpoint-apm/pinpoint · error · IllegalStateException

Invalid type provider definition :

Error message

Invalid type provider definition : 

What it means

TraceMetadataProviderYamlParser.parse(URL) loads a type-provider definition from a URL and converts its parsed service types and annotation keys. Any exception during that conversion (e.g. the empty-name check in toServiceTypeInfo) is wrapped in an IllegalStateException with the URL appended, marking the whole provider definition as invalid.

Source

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

/**
 * @author HyunGil Jeong
 */
public class TraceMetadataProviderYamlParser implements TraceMetadataProviderParser {

    private final Logger logger = LogManager.getLogger(this.getClass());
    private final ObjectMapper mapper = new ObjectMapper(new YAMLFactory());

    @Override
    public ParsedTraceMetadataProvider parse(URL url) {
        String typeProviderId = getTypeProviderId(url);
        try {
            ParsedTraceMetadata parsedTraceMetadata = parse0(url);
            try {List<ServiceTypeInfo> serviceTypeInfos = toServiceTypeInfos(parsedTraceMetadata.getServiceTypes());
                List<AnnotationKey> annotationKeys = toAnnotationKeys(parsedTraceMetadata.getAnnotationKeys());
                return new ParsedTraceMetadataProvider(typeProviderId, serviceTypeInfos, annotationKeys);
            } catch (Exception e) {
                throw new IllegalStateException("Invalid type provider definition : " + url.toString(), e);
            }
        } catch (IOException e) {
            throw new IllegalStateException("IOException parsing " + url.toExternalForm(), e);
        }
    }

    private ParsedTraceMetadata parse0(URL metaUrl) throws IOException {
        try (InputStream inputStream = metaUrl.openStream()) {
            ParsedTraceMetadata parsedTraceMetadata = mapper.readValue(inputStream, ParsedTraceMetadata.class);
            if (parsedTraceMetadata == null) {
                logger.warn("Empty type provider definition. Skipping : {}", metaUrl.toExternalForm());
            }
            return parsedTraceMetadata;
        } catch (JsonParseException | JsonMappingException e) {
            throw new IllegalStateException("Error parsing yml : " + metaUrl, e);
        } catch (IOException e) {
            throw new IllegalStateException("Error opening stream : " + metaUrl, e);
        }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Read the chained cause (e) — it names the exact field that failed validation
2. Fix the offending entry in the YAML at the reported URL (commonly an empty serviceType name or bad annotationKey)
3. Validate the YAML locally with TraceMetadataProviderYamlParser before packaging
4. Ensure the plugin's pinpoint-metadata yaml matches the schema for your Pinpoint version

Example fix

// before
serviceTypes:
  - code: 1000
// after (add required name)
serviceTypes:
  - code: 1000
    name: "MY_SERVICE"

try {
    new TraceMetadataProviderYamlParser().parse(providerUrl);
} catch (IllegalStateException e) {
    e.getCause().printStackTrace(); // names the failing field
}

try {
    parser.parse(url);
} catch (IllegalStateException e) {
    // inspect e.getCause() for the exact invalid entry and fix the YAML
}

When it happens

Trigger: Calling parse(url) where the URL points to a type-provider YAML whose contents fail post-parse conversion — e.g. a serviceTypes entry with an empty name, or an invalid annotationKey entry.

Common situations: Shipping a malformed type-provider yml inside a plugin jar; YAML valid to Jackson but semantically invalid to Pinpoint's checks; plugin version mismatch with the expected schema.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• service type name must not be empty
• annotationKey name must not be empty
• matcher type must not be empty
• Unknown matcher type :
• Error parsing yml :

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