{"record":{"id":"b315ee2a4d289a60","repo":"Netflix/Hystrix","slug":"classsimplename-implementation-class-not-found","errorCode":null,"errorMessage":"${classSimpleName} implementation class not found: ${implementingClass}","messagePattern":"(.+?) implementation class not found: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hystrix-core/src/main/java/com/netflix/hystrix/strategy/HystrixPlugins.java","lineNumber":354,"sourceCode":"        return findService(pluginClass, classLoader);\n    }\n    \n    @SuppressWarnings(\"unchecked\")\n    private static <T> T getPluginImplementationViaProperties(Class<T> pluginClass, HystrixDynamicProperties dynamicProperties) {\n        String classSimpleName = pluginClass.getSimpleName();\n        // Check Archaius for plugin class.\n        String propertyName = \"hystrix.plugin.\" + classSimpleName + \".implementation\";\n        String implementingClass = dynamicProperties.getString(propertyName, null).get();\n        if (implementingClass != null) {\n            try {\n                Class<?> cls = Class.forName(implementingClass);\n                // narrow the scope (cast) to the type we're expecting\n                cls = cls.asSubclass(pluginClass);\n                return (T) cls.newInstance();\n            } catch (ClassCastException e) {\n                throw new RuntimeException(classSimpleName + \" implementation is not an instance of \" + classSimpleName + \": \" + implementingClass);\n            } catch (ClassNotFoundException e) {\n                throw new RuntimeException(classSimpleName + \" implementation class not found: \" + implementingClass, e);\n            } catch (InstantiationException e) {\n                throw new RuntimeException(classSimpleName + \" implementation not able to be instantiated: \" + implementingClass, e);\n            } catch (IllegalAccessException e) {\n                throw new RuntimeException(classSimpleName + \" implementation not able to be accessed: \" + implementingClass, e);\n            }\n        } else {\n            return null;\n        }\n    }\n    \n    \n\n    private static HystrixDynamicProperties resolveDynamicProperties(ClassLoader classLoader, LoggerSupplier logSupplier) {\n        HystrixDynamicProperties hp = getPluginImplementationViaProperties(HystrixDynamicProperties.class, \n                HystrixDynamicPropertiesSystemProperties.getInstance());\n        if (hp != null) {\n            logSupplier.getLogger().debug(\n                    \"Created HystrixDynamicProperties instance from System property named \"","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/Netflix/Hystrix/blob/5ce3bc58c38e7ca60ef2fe0e516e390e294ad941/hystrix-core/src/main/java/com/netflix/hystrix/strategy/HystrixPlugins.java#L336-L372","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify Class.forName(\"com.example.YourStrategy\") succeeds in the same runtime that loads Hystrix, and fix the FQCN typo.","Add the jar containing the strategy class to the application classpath (or the same classloader realm as hystrix-core).","If classloader isolation is the issue, register the plugin programmatically via HystrixPlugins.getInstance().register*(...) instead of the property."],"exampleFix":"# before\nhystrix.plugin.HystrixPropertiesStrategy.implementation=com.example.MyPropertysStrategy   # typo\n\n# after\nhystrix.plugin.HystrixPropertiesStrategy.implementation=com.example.MyPropertiesStrategy","handlingStrategy":"validation","validationCode":"String fqcn = System.getProperty(\"hystrix.plugin.HystrixPropertiesStrategy.implementation\");\nif (fqcn != null) {\n    Class.forName(fqcn); // throws ClassNotFoundException early with your own context\n}","typeGuard":null,"tryCatchPattern":"try {\n    Class.forName(fqcn);\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Invalid hystrix plugin property: class \" + fqcn + \" not on classpath\", e);\n}","preventionTips":["Validate every hystrix.plugin.*.implementation property at startup with Class.forName.","Keep strategy classes in the same deployment artifact as hystrix-core."],"tags":["hystrix","configuration","classpath","reflection"],"backgroundTag":null,"analyzedSha":"5ce3bc58c38e7ca60ef2fe0e516e390e294ad941","analyzedAt":"2026-08-14T10:55:35.600Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}