Netflix/Hystrix · error · RuntimeException

${classSimpleName} implementation is not an instance of ${cl

Error message

${classSimpleName} implementation is not an instance of ${classSimpleName}: ${implementingClass}

What it means

When a plugin implementation is supplied via the property hystrix.plugin.<PluginSimpleName>.implementation, Hystrix loads the class reflectively and calls Class.asSubclass(pluginClass). If the named class does not extend/implement the expected Hystrix strategy type, a ClassCastException is caught and rethrown as this RuntimeException naming the offending class.

Source

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

        T p = getPluginImplementationViaProperties(pluginClass, dynamicProperties);
        if (p != null) return p;        
        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) {

View on GitHub (pinned to 5ce3bc58c3)

Solutions

Make the configured class extend the exact strategy interface named in the property key (e.g. class MyPublisher implements HystrixMetricsPublisher).
Verify the class hierarchy with a quick check: MyPublisher.class.asSubclass(HystrixMetricsPublisher.class) should not throw.
Correct the property value/className typo so it names a class of the right type.

Example fix

// before
-Dhystrix.plugin.HystrixMetricsPublisher.implementation=com.example.SomeRandomClass

// after
public class SomeRandomClass implements HystrixMetricsPublisher { ... }
// or point the property at a class that already implements HystrixMetricsPublisher

Defensive patterns

Strategy: type-guard

Validate before calling

String fqcn = System.getProperty("hystrix.plugin.HystrixMetricsPublisher.implementation");
if (fqcn != null) {
    Class<?> cls = Class.forName(fqcn);
    if (!HystrixMetricsPublisher.class.isAssignableFrom(cls)) {
        throw new IllegalStateException(fqcn + " does not implement HystrixMetricsPublisher");
    }
}

Type guard

static boolean isValidPlugin(Class<?> candidate, Class<?> pluginInterface) {
    return pluginInterface.isAssignableFrom(candidate);
}

Try / catch

try {
    // trigger plugin resolution (first getter call)
    HystrixPlugins.getInstance().getMetricsPublisher();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("is not an instance of")) {
        // fix the hystrix.plugin.*.implementation property value
    }
}

Prevention

Add a startup assertion that each configured plugin class is assignable to its strategy interface.
Generate plugin config from a typed registry rather than free-form property strings.

When it happens

Trigger: Setting e.g. -Dhystrix.plugin.HystrixMetricsPublisher.implementation=com.example.MyNotAPublisher where MyNotAPublisher does not extend HystrixMetricsPublisher (wrong superclass, wrong interface, or a class that only extends another plugin type).

Common situations: Copy-pasting an Archaius property from a different plugin; renaming a strategy class so it no longer extends the base; pointing the wrong plugin key at a class written for a different strategy interface.

Related errors

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