What causes "{} define fail cl:{} Caused by:{}" in pinpoint-apm/pinpoint?

Read 'Caused by' in the RuntimeException for the underlying reason (LinkageError, SecurityException, etc.)

{} define fail cl:{} Caused by:{}

Error message

{} define fail cl:{} Caused by:{}

What it means

Java9DefineClass.defineClass uses JavaLangAccess.defineClass (shared secrets API) to inject transformed classes into a classloader on JDK 9+. Any failure of that internal define call is caught, logged as '<name> define fail cl:<classLoader> Caused by:<msg>', and rethrown as a RuntimeException. This means bytecode transformation succeeded but the class could not be defined into the target loader.

Source

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

import org.apache.logging.log4j.Logger;

/**
 * @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

Read 'Caused by' in the RuntimeException for the underlying reason (LinkageError, SecurityException, etc.)
Check the target JDK build is one supported by this Pinpoint version; upgrade Pinpoint agent for newer JDKs
Verify the transformed bytecode's internal class name matches the 'name' passed to defineClass
If a module/sealing issue, add --add-exports for jdk.internal.misc or run the agent on a compatible JVM

Defensive patterns

Strategy: try-catch

Validate before calling

// JDK capability check before instrumenting
Class<?> acc = Class.forName("jdk.internal.misc.JavaLangAccess", false, null);

Try / catch

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(...); }

Prevention

Keep agent and JDK versions matched to Pinpoint's compatibility matrix
Never transform bytecode in ways that change the class's internal name
Watch for JDK internal API moves (jdk.internal.misc -> jdk.internal.access)

When it happens

Trigger: Calling defineClass with bytes whose class name does not match 'name', a classLoader rejected by javaLangAccess.defineClass (e.g. null incompatibility), or on a JDK where jdk.internal.misc.JavaLangAccess.defineClass signature changed.

Common situations: Upgrading to a JDK 9/10/11 early-access build where the internal JavaLangAccess API changed; duplicate class definition for the same loader; sealed packages or module access restrictions blocking definition.

Related errors

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