pinpoint-apm/pinpoint · error · IllegalStateException

I/O error getting type provider definitions

Error message

I/O error getting type provider definitions

What it means

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.

Source

Thrown at agent-module/plugins-loader/src/main/java/com/navercorp/pinpoint/loader/plugins/trace/TraceMetadataProviderLoader.java:144

        for (URL customTypeProviderUrl : customTypeProviderUrls) {
            if (pluginTypeProviderUrlFilter.filter(customTypeProviderUrl)) {
                continue;
            }
            typeProviderUrls.add(customTypeProviderUrl);
        }

        try {
            Enumeration<URL> pluginTypeProviderUrls = classLoader.getResources(typeProviderDefEntry);
            while (pluginTypeProviderUrls.hasMoreElements()) {
                URL pluginTypeProviderUrl = pluginTypeProviderUrls.nextElement();
                if (pluginTypeProviderUrlFilter.filter(pluginTypeProviderUrl)) {
                    continue;
                }

                typeProviderUrls.add(pluginTypeProviderUrl);
            }
        } catch (IOException e) {
            throw new IllegalStateException("I/O error getting type provider definitions", e);
        }
        return typeProviderUrls;
    }

    private List<TraceMetadataProvider> fromServiceLoader(ClassLoader classLoader) {
        List<TraceMetadataProvider> traceMetadataProviders = new ArrayList<>();
        ServiceLoader<TraceMetadataProvider> serviceLoader = ServiceLoader.load(TraceMetadataProvider.class, classLoader);
        for (TraceMetadataProvider traceMetadataProvider : serviceLoader) {
            traceMetadataProviders.add(new LoadedTraceMetadataProvider(traceMetadataProvider));
        }
        return traceMetadataProviders;
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Inspect the wrapped IOException cause for the exact failing resource/jar
  2. Test each plugin jar with 'unzip -t' and remove/replace corrupt jars
  3. Check read permissions on the agent plugins directory and its jars
  4. Restart the agent after ensuring plugins are fully deployed (no partial uploads)

Example fix

// before
/plugins/foo-plugin.jar // truncated upload, unreadable during getResources scan -> I/O error
// after
# verify: unzip -t /agent/plugins/foo-plugin.jar && chmod 644 /agent/plugins/*.jar
// restart agent
Defensive patterns

Strategy: try-catch

Validate before calling

for (Path jar : pluginDirJars) {
  if (!Files.isReadable(jar)) throw new IllegalStateException("unreadable plugin: " + jar);
  try (java.util.zip.ZipFile z = new java.util.zip.ZipFile(jar.toFile())) { } catch (IOException e) { throw new IllegalStateException("corrupt plugin: " + jar, e); }
}

Try / catch

try { providers = TraceMetadataProviderLoader.load(classLoader); } catch (IllegalStateException e) { log.error("type provider scan failed: {}", e.getCause(), e); throw e; }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

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

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