pinpoint-apm/pinpoint · error · IOException

not found template class resource

Error message

not found template class resource 

What it means

ASMGuardedInterceptorFactory.readTemplateBytes() opens the class resource for a template class; if openTemplateStream() returns null the template class resource cannot be located on the classpath, and an IOException is thrown. The factory needs the template bytecode to rewrite interceptor templates; without it weaving cannot continue.

Solutions

1. Ensure the template class file is packaged in the plugin jar
2. Check which classloader is used to open the resource and verify visibility
3. Rebuild/redeploy the plugin jar if class files were stripped by the build (e.g. shading exclusions)
4. Log the template class name and verify with jar tf that the resource exists

Example fix

// build fix: keep class resources in shade plugin
// before
<exclude>**/template/**</exclude>
// after
<!-- remove the exclusion so template classes ship in the jar -->

// Verify the template resource is resolvable before weaving
if (template.getClassLoader().getResource(template.getName().replace('.', '/') + ".class") == null) {
    throw new IllegalStateException("template class resource missing: " + template.getName());
}

try {
    factory.newInterceptor(...);
} catch (IOException e) {
    logger.error("template resource missing: {}", e.getMessage());
}

When it happens

Trigger: rewriteTemplate calls readTemplateBytes for a template Class whose .class resource cannot be obtained as a stream (openTemplateStream returns null).

Common situations: Template class not present in the jar; template class generated/renamed; classloader cannot return the resource (special classloaders, shaded jars); packaging stripped class files.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• AnnotationKey code of
• banner IO failed
• boot class not found. bootClass: Error:
• I/O error getting type provider definitions
• Invalid pinpoint-bootstrap.jar:

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

Appendix: source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/ASMGuardedInterceptorFactory.java:281

        final String concreteInternalName = Type.getInternalName(delegateClass);

        final Map<String, String> mapping = new HashMap<>();
        mapping.put(Type.getInternalName(template), newInternalName);
        mapping.put(baseInterfaceInternalName, concreteInternalName);

        final ClassReader classReader = new ClassReader(templateBytes);
        // COMPUTE_MAXS: instructions are unchanged, but descriptors change length. EXPAND_FRAMES
        // because the remapper requires expanded frames to retype their entries.
        final ClassWriter classWriter = new ClassWriter(ClassWriter.COMPUTE_MAXS);
        final ClassRemapper remapper = new RetypingClassRemapper(classWriter, new SimpleRemapper(mapping), concreteInternalName);
        classReader.accept(remapper, ClassReader.EXPAND_FRAMES);
        return classWriter.toByteArray();
    }

    private static byte[] readTemplateBytes(Class<?> template) throws IOException {
        final InputStream inputStream = openTemplateStream(template);
        if (inputStream == null) {
            throw new IOException("not found template class resource " + template.getName());
        }
        try {
            return IOUtils.toByteArray(inputStream);
        } finally {
            inputStream.close();
        }
    }

    private static InputStream openTemplateStream(Class<?> template) {
        final InputStream inputStream = template.getResourceAsStream(template.getSimpleName() + ".class");
        if (inputStream != null) {
            return inputStream;
        }
        final BootstrapCore bootstrapCore = templateSource;
        if (bootstrapCore != null) {
            final String resourceName = JavaAssistUtils.javaNameToJvmName(template.getName()) + ".class";
            return bootstrapCore.openStream(resourceName);
        }

View on GitHub (pinned to 744c3d3075)