{"record":{"id":"1ef6079a810388b3","repo":"apache/flink","slug":"class-s-not-found-perhaps-you-forgot-to-add-th","errorCode":null,"errorMessage":"Class '%s' not found. Perhaps you forgot to add the module '%s' to the classpath?","messagePattern":"Class '(.+?)' not found\\. Perhaps you forgot to add the module '(.+?)' to the classpath\\?","errorType":"exception","errorClass":"ClassNotFoundException","httpStatus":null,"severity":"critical","filePath":"flink-core/src/main/java/org/apache/flink/core/classloading/ComponentClassLoader.java","lineNumber":122,"sourceCode":"                    return loadClassFromComponentFirst(name, resolve);\n                }\n                if (isOwnerFirstClass(name)) {\n                    return loadClassFromOwnerFirst(name, resolve);\n                }\n\n                // making this behavior configurable (component-only/component-first/owner-first)\n                // would allow this class to subsume the FlinkUserCodeClassLoader (with an added\n                // exception handler)\n                return loadClassFromComponentOnly(name, resolve);\n            } catch (ClassNotFoundException e) {\n                // If we know the package of this class\n                Optional<String> foundAssociatedModule =\n                        knownPackagePrefixesModuleAssociation.entrySet().stream()\n                                .filter(entry -> name.startsWith(entry.getKey()))\n                                .map(Map.Entry::getValue)\n                                .findFirst();\n                if (foundAssociatedModule.isPresent()) {\n                    throw new ClassNotFoundException(\n                            String.format(\n                                    \"Class '%s' not found. Perhaps you forgot to add the module '%s' to the classpath?\",\n                                    name, foundAssociatedModule.get()),\n                            e);\n                }\n                throw e;\n            }\n        }\n    }\n\n    private Class<?> resolveIfNeeded(final boolean resolve, final Class<?> loadedClass) {\n        if (resolve) {\n            resolveClass(loadedClass);\n        }\n        return loadedClass;\n    }\n\n    private boolean isOwnerFirstClass(final String name) {","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/core/classloading/ComponentClassLoader.java#L104-L140","documentation":"Thrown by ComponentClassLoader.loadClass when a class cannot be found in the component classloader and the class's package prefix matches a known module association. The error enriches the raw ClassNotFoundException with a hint about which module likely provides the missing class.","triggerScenarios":"A class whose package (e.g., org.apache.flink.table.*) is associated with a known module (e.g., flink-table) but that module's JAR is not on the classpath. The classloader tried component-only, owner, etc. and fell through to the catch block.","commonSituations":"Running Flink without the table planner JAR when executing SQL/Table API jobs. Missing connector JARs in the lib directory. Deploying a slim distribution that omits needed modules. Version mismatch where a module was renamed or split.","solutions":["Add the named module JAR to the Flink lib directory or your job's classpath.","Verify the module version matches your Flink distribution version.","If the module should be present, check for classloader isolation issues or shaded dependency conflicts."],"exampleFix":"# before: missing planner\n# job fails with Class 'org.apache.flink.table.planner...' not found, module 'flink-table-planner-loader'\n\n# after: add the JAR to lib\ncp flink-table-planner-loader-*.jar $FLINK_HOME/lib/","handlingStrategy":"validation","validationCode":"// Before launching, verify required module JARs are present\nPath libDir = Paths.get(flinkHome, \"lib\");\nList<String> required = List.of(\"flink-table-planner\", \"flink-clients\");\nfor (String mod : required) {\n    try (Stream<Path> files = Files.list(libDir)) {\n        if (files.noneMatch(p -> p.getFileName().toString().startsWith(mod))) {\n            throw new IllegalStateException(\"Missing module JAR: \" + mod);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Class.forName(className);\n} catch (ClassNotFoundException e) {\n    if (e.getMessage().contains(\"forgot to add the module\")) { /* add the named module JAR */ }\n}","preventionTips":["Ensure all required module JARs are in $FLINK_HOME/lib or on the job classpath.","Match module versions to the Flink distribution version.","Include the table planner loader when using SQL/Table API."],"tags":["classloading","classpath","module","deployment"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}