{"record":{"id":"16ad865d9c440887","repo":"pinpoint-apm/pinpoint","slug":"i-o-error-getting-type-provider-definitions","errorCode":null,"errorMessage":"I/O error getting type provider definitions","messagePattern":"I/O error getting type provider definitions","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agent-module/plugins-loader/src/main/java/com/navercorp/pinpoint/loader/plugins/trace/TraceMetadataProviderLoader.java","lineNumber":144,"sourceCode":"        for (URL customTypeProviderUrl : customTypeProviderUrls) {\n            if (pluginTypeProviderUrlFilter.filter(customTypeProviderUrl)) {\n                continue;\n            }\n            typeProviderUrls.add(customTypeProviderUrl);\n        }\n\n        try {\n            Enumeration<URL> pluginTypeProviderUrls = classLoader.getResources(typeProviderDefEntry);\n            while (pluginTypeProviderUrls.hasMoreElements()) {\n                URL pluginTypeProviderUrl = pluginTypeProviderUrls.nextElement();\n                if (pluginTypeProviderUrlFilter.filter(pluginTypeProviderUrl)) {\n                    continue;\n                }\n\n                typeProviderUrls.add(pluginTypeProviderUrl);\n            }\n        } catch (IOException e) {\n            throw new IllegalStateException(\"I/O error getting type provider definitions\", e);\n        }\n        return typeProviderUrls;\n    }\n\n    private List<TraceMetadataProvider> fromServiceLoader(ClassLoader classLoader) {\n        List<TraceMetadataProvider> traceMetadataProviders = new ArrayList<>();\n        ServiceLoader<TraceMetadataProvider> serviceLoader = ServiceLoader.load(TraceMetadataProvider.class, classLoader);\n        for (TraceMetadataProvider traceMetadataProvider : serviceLoader) {\n            traceMetadataProviders.add(new LoadedTraceMetadataProvider(traceMetadataProvider));\n        }\n        return traceMetadataProviders;\n    }\n}\n","sourceCodeStart":126,"sourceCodeEnd":158,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/plugins-loader/src/main/java/com/navercorp/pinpoint/loader/plugins/trace/TraceMetadataProviderLoader.java#L126-L158","documentation":"Thrown by TraceMetadataProviderLoader.getTypeProviderUrls when an IOException occurs while scanning for META-INF type-provider definition files (e.g. reading directory/classloader URLs). It is wrapped in an IllegalStateException since the plugin metadata cannot be loaded without these definitions.","triggerScenarios":"Classloader resource enumeration (getResources on the type-provider meta-inf path) throws IOException — e.g. a jar in the classpath is unreadable/corrupt, or an I/O error occurs while reading the plugins directory.","commonSituations":"Corrupt or unreadable plugin jar in the plugins directory; plugin removed/replaced while the agent was starting; filesystem errors on network-mounted agent dirs; classloader quirks with unusual resources.","solutions":["Inspect the wrapped IOException cause for the exact failing resource/jar","Test each plugin jar with 'unzip -t' and remove/replace corrupt jars","Check read permissions on the agent plugins directory and its jars","Restart the agent after ensuring plugins are fully deployed (no partial uploads)"],"exampleFix":"// before\n/plugins/foo-plugin.jar // truncated upload, unreadable during getResources scan -> I/O error\n// after\n# verify: unzip -t /agent/plugins/foo-plugin.jar && chmod 644 /agent/plugins/*.jar\n// restart agent","handlingStrategy":"try-catch","validationCode":"for (Path jar : pluginDirJars) {\n  if (!Files.isReadable(jar)) throw new IllegalStateException(\"unreadable plugin: \" + jar);\n  try (java.util.zip.ZipFile z = new java.util.zip.ZipFile(jar.toFile())) { } catch (IOException e) { throw new IllegalStateException(\"corrupt plugin: \" + jar, e); }\n}","typeGuard":null,"tryCatchPattern":"try { providers = TraceMetadataProviderLoader.load(classLoader); } catch (IllegalStateException e) { log.error(\"type provider scan failed: {}\", e.getCause(), e); throw e; }","preventionTips":["Validate plugin jars after deployment (unzip -t)","Deploy plugins atomically — never replace jars while the agent runs","Ensure consistent permissions on the plugins directory","Avoid network-mounted agent dirs prone to I/O errors"],"tags":["java","plugin-loader","io","classpath"],"backgroundTag":"file-read-failed","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}