Netflix/Hystrix · error · RuntimeException

${classSimpleName} implementation class not found: ${impleme

Error message

${classSimpleName} implementation class not found: ${implementingClass}

What it means

Hystrix resolves plugin implementations from the property hystrix.plugin.<PluginSimpleName>.implementation using Class.forName on the configured FQCN. If the class is not loadable from Hystrix's classloader, the ClassNotFoundException is wrapped in this RuntimeException. The original exception is attached as the cause.

Source

Thrown at hystrix-core/src/main/java/com/netflix/hystrix/strategy/HystrixPlugins.java:354

        return findService(pluginClass, classLoader);
    }
    
    @SuppressWarnings("unchecked")
    private static <T> T getPluginImplementationViaProperties(Class<T> pluginClass, HystrixDynamicProperties dynamicProperties) {
        String classSimpleName = pluginClass.getSimpleName();
        // Check Archaius for plugin class.
        String propertyName = "hystrix.plugin." + classSimpleName + ".implementation";
        String implementingClass = dynamicProperties.getString(propertyName, null).get();
        if (implementingClass != null) {
            try {
                Class<?> cls = Class.forName(implementingClass);
                // narrow the scope (cast) to the type we're expecting
                cls = cls.asSubclass(pluginClass);
                return (T) cls.newInstance();
            } catch (ClassCastException e) {
                throw new RuntimeException(classSimpleName + " implementation is not an instance of " + classSimpleName + ": " + implementingClass);
            } catch (ClassNotFoundException e) {
                throw new RuntimeException(classSimpleName + " implementation class not found: " + implementingClass, e);
            } catch (InstantiationException e) {
                throw new RuntimeException(classSimpleName + " implementation not able to be instantiated: " + implementingClass, e);
            } catch (IllegalAccessException e) {
                throw new RuntimeException(classSimpleName + " implementation not able to be accessed: " + implementingClass, e);
            }
        } else {
            return null;
        }
    }
    
    

    private static HystrixDynamicProperties resolveDynamicProperties(ClassLoader classLoader, LoggerSupplier logSupplier) {
        HystrixDynamicProperties hp = getPluginImplementationViaProperties(HystrixDynamicProperties.class, 
                HystrixDynamicPropertiesSystemProperties.getInstance());
        if (hp != null) {
            logSupplier.getLogger().debug(
                    "Created HystrixDynamicProperties instance from System property named "

View on GitHub (pinned to 5ce3bc58c3)

Solutions

  1. Verify Class.forName("com.example.YourStrategy") succeeds in the same runtime that loads Hystrix, and fix the FQCN typo.
  2. Add the jar containing the strategy class to the application classpath (or the same classloader realm as hystrix-core).
  3. If classloader isolation is the issue, register the plugin programmatically via HystrixPlugins.getInstance().register*(...) instead of the property.

Example fix

# before
hystrix.plugin.HystrixPropertiesStrategy.implementation=com.example.MyPropertysStrategy   # typo

# after
hystrix.plugin.HystrixPropertiesStrategy.implementation=com.example.MyPropertiesStrategy
Defensive patterns

Strategy: validation

Validate before calling

String fqcn = System.getProperty("hystrix.plugin.HystrixPropertiesStrategy.implementation");
if (fqcn != null) {
    Class.forName(fqcn); // throws ClassNotFoundException early with your own context
}

Try / catch

try {
    Class.forName(fqcn);
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Invalid hystrix plugin property: class " + fqcn + " not on classpath", e);
}

Prevention

When it happens

Trigger: Setting the property to a misspelled or outdated fully-qualified class name; the class lives in a jar not on the application classpath; in an app-server/OSGi environment the class is visible to the webapp classloader but Class.forName uses a different one.

Common situations: Typos in the Archaius/config property value; upgrading a library that renamed or moved the strategy class; fat-jar/shaded-jar builds stripping the class; deployment-time classloader isolation in Tomcat/WebLogic.

Related errors

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