{"record":{"id":"bdc8adf6121c851f","repo":"apache/flink","slug":"the-program-s-entry-point-class-classname-coul","errorCode":null,"errorMessage":"The program's entry point class '{className}' could not be loaded due to a linkage failure.","messagePattern":"The program's entry point class '(.+?)' could not be loaded due to a linkage failure\\.","errorType":"exception","errorClass":"ProgramInvocationException","httpStatus":null,"severity":"critical","filePath":"flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgram.java","lineNumber":497,"sourceCode":"        ClassLoader contextCl = null;\n        try {\n            contextCl = Thread.currentThread().getContextClassLoader();\n            Thread.currentThread().setContextClassLoader(cl);\n            return Class.forName(className, false, cl);\n        } catch (ClassNotFoundException e) {\n            throw new ProgramInvocationException(\n                    \"The program's entry point class '\"\n                            + className\n                            + \"' was not found in the jar file.\",\n                    e);\n        } catch (ExceptionInInitializerError e) {\n            throw new ProgramInvocationException(\n                    \"The program's entry point class '\"\n                            + className\n                            + \"' threw an error during initialization.\",\n                    e);\n        } catch (LinkageError e) {\n            throw new ProgramInvocationException(\n                    \"The program's entry point class '\"\n                            + className\n                            + \"' could not be loaded due to a linkage failure.\",\n                    e);\n        } catch (Throwable t) {\n            throw new ProgramInvocationException(\n                    \"The program's entry point class '\"\n                            + className\n                            + \"' caused an exception during initialization: \"\n                            + t.getMessage(),\n                    t);\n        } finally {\n            if (contextCl != null) {\n                Thread.currentThread().setContextClassLoader(contextCl);\n            }\n        }\n    }\n","sourceCodeStart":479,"sourceCodeEnd":515,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgram.java#L479-L515","documentation":"Thrown when Class.forName encounters a LinkageError (e.g., NoClassDefFoundError, UnsatisfiedLinkError, VerifyError, IncompatibleClassChangeError) for the entry point class. The class was found but could not be linked — typically a missing transitive dependency at link time or a native library issue.","triggerScenarios":"Entry point class references another class (in a static field type, method signature, or superclass) that is not on the classpath. Also triggered by JVM verifier rejection (VerifyError) or missing native library (UnsatisfiedLinkError).","commonSituations":"Jar bundles an incompatible version of a dependency, classpath conflict between Flink runtime classes and user jar, shaded dependency references that are incomplete, or a native library (.so/.dylib) missing in the container.","solutions":["Inspect the chained LinkageError cause — for NoClassDefFoundError, note the missing class and add it to the jar or user classpath.","Check for dependency version conflicts (use 'mvn dependency:tree' or shade plugin analysis).","For UnsatisfiedLinkError, ensure native libraries are present and java.library.path is set.","For VerifyError, recompile the jar with a compatible JDK version (match Java 11/17 target)."],"exampleFix":"// before: NoClassDefFoundError for com.fasterxml.jackson.databind.ObjectMapper\n// (dependency shaded out or missing)\n\n// after: add to pom.xml or shade include\n<dependency>\n  <groupId>com.fasterxml.jackson.core</groupId>\n  <artifactId>jackson-databind</artifactId>\n</dependency>","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    PackagedProgram.newBuilder()\n        .setJarFile(jarFile)\n        .setEntryPointClassName(className)\n        .build();\n} catch (ProgramInvocationException e) {\n    if (e.getCause() instanceof LinkageError) {\n        LinkageError le = (LinkageError) e.getCause();\n        // inspect le for missing class / native lib / verify error\n    }\n    throw e;\n}","preventionTips":["Use 'mvn dependency:tree' to detect version conflicts before packaging.","Bundle all runtime dependencies in a fat jar or configure the maven shade plugin correctly.","Match JDK compilation target to the runtime JDK version."],"tags":["packaged-program","class-loading","linkage-error","dependency","classpath"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}