{"record":{"id":"968a3fc65f896354","repo":"flowable/flowable-engine","slug":"could-not-load-class-classname-or-class-not","errorCode":null,"errorMessage":"Could not load class: ${className} (or 'Class not found: ${className}' when cause is ClassNotFoundException)","messagePattern":"Could not load class: (.+?) \\(or 'Class not found: (.+?)' when cause is ClassNotFoundException\\)","errorType":"exception","errorClass":"FlowableClassLoadingException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/util/ReflectUtil.java","lineNumber":89,"sourceCode":"            } catch (Throwable t) {\n                if (throwable == null) {\n                    throwable = t;\n                }\n            }\n            if (clazz == null) {\n                try {\n                    LOGGER.trace(\"Trying to load class with local classloader: {}\", className);\n                    clazz = loadClass(ReflectUtil.class.getClassLoader(), className);\n                } catch (Throwable t) {\n                    if (throwable == null) {\n                        throwable = t;\n                    }\n                }\n            }\n        }\n\n        if (clazz == null) {\n            throw new FlowableClassLoadingException(className, throwable);\n        }\n        return clazz;\n    }\n\n    public static boolean isClassPresent(String className) {\n        try {\n            loadClass(className);\n            return true;\n        } catch (FlowableClassLoadingException ignored) {\n            return false;\n        }\n    }\n\n    public static InputStream getResourceAsStream(String name) {\n        InputStream resourceStream = null;\n        ClassLoader classLoader = getCustomClassLoader();\n        if (classLoader != null) {\n            resourceStream = classLoader.getResourceAsStream(name);","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/util/ReflectUtil.java#L71-L107","documentation":"ReflectUtil.loadClass tries the context classloader, the current class's classloader, and other fallbacks to load a class by name; if all attempts fail it throws FlowableClassLoadingException with the message 'Could not load class: X' (or 'Class not found: X' when the root cause is a ClassNotFoundException). The real cause (LinkageError, security issue, etc.) is attached.","triggerScenarios":"Calling ReflectUtil.loadClass(className) or isClassPresent-dependent code paths with a class name that is misspelled, not on the classpath, or whose static initializer/linking fails.","commonSituations":"Configuring custom classes (delegates, listeners, serializers) in process XML or config with wrong fully-qualified names; dependencies missing at runtime in fat jars/containers; class exists in a provided-scope dependency not packaged; Java version mismatch breaking linking.","solutions":["Verify the fully-qualified class name in your configuration is spelled correctly and case-exact.","Confirm the class is on the runtime classpath (check the packaged jar/war, mvn dependency:tree).","Inspect the 'cause' of FlowableClassLoadingException: ClassNotFoundException means missing; NoClassDefFoundError/LinkageError means dependency version conflict.","Add the missing dependency or fix its scope (compile instead of provided/test).","If using OSGi or custom classloaders, ensure ReflectUtil can find the class via the thread context classloader."],"exampleFix":"// before\n<flowable:class delegateExpression=\"com.acme.MyDelegate\"/>  <!-- wrong name -->\n// after\n<!-- exact FQN of a class present on the runtime classpath -->\n<flowable:class delegateExpression=\"com.acme.order.MyJavaDelegate\"/>","handlingStrategy":"try-catch","validationCode":"if (!ReflectUtil.isClassPresent(className)) {\n    throw new IllegalStateException(\"Class not on classpath: \" + className);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Class<?> c = ReflectUtil.loadClass(className);\n} catch (FlowableClassLoadingException e) {\n    LOGGER.error(\"Cannot load {}: {}\", className, e.getCause(), e);\n    throw newConfigurationException(className, e.getCause());\n}","preventionTips":["Keep fully-qualified class names in config in sync with refactors","Check dependency scopes so runtime-needed classes are packaged","Inspect e.getCause(): ClassNotFoundException vs NoClassDefFoundError indicate different fixes","Run smoke tests in the packaged artifact, not just the IDE"],"tags":["classpath","reflection","class-not-found","java"],"backgroundTag":"class-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}