Netflix/Hystrix · critical · RuntimeException

Failed trying to wrap class: " + className

Error message

Failed trying to wrap class: " + className

What it means

NetworkClassTransform is the javaagent's ClassFileTransformer: when the JVM loads java.net.Socket$2 or java.nio.channels.SocketChannel it uses Javassist (ClassPool/CtClass) to instrument them so each network operation notifies HystrixNetworkAuditorAgent. Any Exception during lookup or transformation (e.g. a JDK whose internal Socket$2 differs, ClassPool missing the class path, CtClass compilation failure) is wrapped in RuntimeException('Failed trying to wrap class: <name>').

Source

Thrown at hystrix-contrib/hystrix-network-auditor-agent/src/main/java/com/netflix/hystrix/contrib/networkauditor/NetworkClassTransform.java:56

        try {
            /*
             * These hook points were found through trial-and-error after wrapping all java.net/java.io/java.nio classes and methods and finding reliable
             * notifications that matched statistics and events in an application.
             * 
             * There may very well be problems here or code paths that don't correctly trigger an event.
             * 
             * If someone can provide a more reliable and cleaner hook point or if there are examples of code paths that don't trigger either of these
             * then please file a bug or submit a pull request at https://github.com/Netflix/Hystrix
             */
            if (name.equals("java.net.Socket$2")) {
                // this one seems to be fairly reliable in counting each time a request/response occurs on blocking IO
                return wrapConstructorsOfClass(name);
            } else if (name.equals("java.nio.channels.SocketChannel")) {
                // handle NIO 
                return wrapConstructorsOfClass(name);
            }
        } catch (Exception e) {
            throw new RuntimeException("Failed trying to wrap class: " + className, e);
        }

        // we didn't transform anything so return null to leave untouched
        return null;
    }

    /**
     * Wrap all constructors of a given class
     * 
     * @param className
     * @throws NotFoundException
     * @throws CannotCompileException
     * @throws IOException
     */
    private byte[] wrapConstructorsOfClass(String className) throws NotFoundException, IOException, CannotCompileException {
        return wrapClass(className, true);
    }

View on GitHub (pinned to 5ce3bc58c3)

Solutions

1. Pin or move to a Java version the agent supports (the transformation targets specific JDK internals of its era)
2. Upgrade hystrix-network-auditor-agent (or drop the auditor) if the JDK internal class it hooks no longer exists — inspect the cause in the stack trace
3. Ensure the agent jar and its javassist dependency are on the boot path: -javaagent:...agent.jar with javassist bundled
4. If the auditor is not essential, remove the -javaagent flag to unblock startup

Example fix

# before (newer JDK, agent fails transforming JDK internals)
java -javaagent:hystrix-network-auditor-agent-1.5.x.jar -jar app.jar

# after (remove unsupported agent or use supported JDK)
java -jar app.jar

String javaVersion = System.getProperty("java.specification.version");
if (!SUPPORTED_JDKS.contains(javaVersion)) {
    log.warn("network-auditor agent unsupported on JDK {} — remove -javaagent or upgrade agent", javaVersion);
}

// in agent bootstrap/premain: isolate and surface transformation failures
try { premainLogic(args, instrumentation); }
catch (RuntimeException e) {
    log.error("network auditor transformation failed ({}); continuing without auditing", e.getMessage(), e);
    // or fail hard if auditing is mandatory: throw e;
}

When it happens

Trigger: Running the network-auditor agent on an unsupported/newer JDK where java.net.Socket$2 internals changed or the anonymous class name differs; ClassPool.getDefault() unable to resolve bootstrap classes (missing -Xbootclasspath inclusion of javassist's search path); Javassist CannotCompileException from inserting before an incompatible constructor.

Common situations: Upgrading the application to a newer Java version while keeping an old hystrix-network-auditor-agent; running on non-HotSpot JVMs; agent jar missing javassist or its classpool configuration on restricted classloaders.

Related errors

• Failed trying to wrap constructor of class: " + className
• HystrixNetworkAuditorEventListener can not be NULL
• Failed trying to wrap method [" + method.getName() + "] of c
• method cannot be annotated with HystrixCommand and HystrixCo
• Collapser method must have one argument: {}

AI-assisted analysis of Netflix/Hystrix@5ce3bc58c3 (2026-08-14). Data as JSON: /api/errors/2e6509a6dbd82f8b. Report an issue: GitHub.