What causes "${name} define fail Caused by:${e.getMessage()}" in pinpoint-apm/pinpoint?

Inspect the wrapped cause 'Caused by' to identify the real failure

pinpoint-apm/pinpoint · error · RuntimeException

${name} define fail Caused by:${e.getMessage()}

Error message

${name} define fail Caused by:${e.getMessage()}

What it means

Java9DefineClass.defineClass uses the shared JavaLangAccess (jdk.internal.misc.SharedSecrets on JDK9+) to inject transformed classes. If JavaLangAccess.defineClass throws any Throwable, it is rethrown as RuntimeException('<name> define fail Caused by:<msg>'). This means the instrumented class could not be defined into the target classloader.

Source

Thrown at agent-module/profiler-optional/profiler-optional-jdk9/src/main/java/com/navercorp/pinpoint/profiler/instrument/classloading/Java9DefineClass.java:40

/**
 * @author Woonduk Kang(emeroad)
 */
final class Java9DefineClass implements DefineClass {

    private final Logger logger = LogManager.getLogger(this.getClass());

    @Override
    public Class<?> defineClass(ClassLoader classLoader, String name, byte[] bytes) {
        if (logger.isDebugEnabled()) {
            logger.debug("define class:{} cl:{}", name, classLoader);
        }
        final JavaLangAccess javaLangAccess = JavaLangAccessHelper.getJavaLangAccess();
        try {
            return javaLangAccess.defineClass(classLoader, name, bytes, null, null);
        } catch (Throwable e) {
            logger.warn("{} define fail cl:{} Caused by:{}", name, classLoader, e.getMessage(), e);
            throw new RuntimeException(name + " define fail Caused by:" + e.getMessage(), e);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

Inspect the wrapped cause 'Caused by' to identify the real failure
Verify the class name matches the bytecode being defined
Check the target classloader/module allows defining in that package (add --add-opens if needed)
Ensure the bytecode transformation produced valid class files
Update Pinpoint to a version compatible with your JDK

Example fix

// before (JDK16+ access failure)
defineClass(clazz, bytes); // RuntimeException define fail
// after: open the package to the agent
java --add-opens java.base/java.lang=ALL-UNNAMED ...

Defensive patterns

Strategy: try-catch

Validate before calling

if (clazz == null || bytes == null || bytes.length == 0 || classLoader == null) {
    throw new IllegalArgumentException("invalid defineClass input");
}

Try / catch

try {
    return javaLangAccess.defineClass(classLoader, name, bytes, null, null);
} catch (Throwable e) {
    logger.warn("define fail {} cl:{}", name, classLoader, e);
    throw new RuntimeException(name + " define fail Caused by:" + e.getMessage(), e);
}

Prevention

Always log the full cause chain when defining classes fails
Validate bytecode and class name consistency before defining
Check module/package openness on JDK9+ before defining
Run on a supported JDK/agent combination

When it happens

Trigger: Calling defineClass on Java9DefineClass when javaLangAccess.defineClass(classLoader, name, bytes, null, null) throws (duplicate class name, security manager denial, bad bytecode, wrong classloader, module access restrictions on JDK9+).

Common situations: JDK upgrade where JavaLangAccess behavior changed; attempts to define a class already defined; defining into a named module's classloader where package is not open; corrupted/transformed bytecode from instrumentation.

Related errors

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