pinpoint-apm/pinpoint · error · IllegalStateException

IOException parsing

Error message

IOException parsing 

What it means

TraceMetadataProviderYamlParser.parse(URL) treats any IOException while opening/reading the provider URL as a fatal problem and wraps it in an IllegalStateException('IOException parsing ' + url). This distinguishes I/O failures from the semantic-conversion failures handled by the other branch.

Source

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

 */
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);
        }
    }

    private String getTypeProviderId(URL metaUrl) {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Confirm the YAML resource actually exists inside the plugin artifact (unzip -l plugin.jar | grep yml)
2. Check the URL/path used to locate the resource matches the packaged location
3. Rebuild the plugin if packaging filtered the resource out
4. Verify read permissions on the file/jar

Example fix

// before: resource not on classpath
URL url = getClass().getResource("/typo-provider.yml");
// after
URL url = getClass().getResource("/pinpoint/type-provider.yml");

URL url = getClass().getResource(path);
if (url == null) {
    throw new FileNotFoundException("missing type provider resource: " + path);
}

try {
    parser.parse(url);
} catch (IllegalStateException e) {
    // message contains 'IOException parsing' — check resource exists/readable, then rethrow or skip provider
}

When it happens

Trigger: The URL passed to parse() cannot be opened or read: stream creation or mapper.readValue throws an IOException other than Jackson's parse/mapping exceptions (which are handled in parse0).

Common situations: Type-provider yml missing from the plugin jar after packaging; wrong classpath resource path; jar corrupted; file permissions on an external resource URL.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Error opening stream :
• Failed to load plugin resource as stream {} with classLoader
• Failed to load plugin resource as stream {} with classLoader
• Failed to load plugin resource as stream {} with classLoader
• bytecode read fail path:{}

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