apache/flink · critical · ProgramInvocationException

The program's entry point class '{className}' could not be l

Error message

The program's entry point class '{className}' could not be loaded due to a linkage failure.

What it means

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.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgram.java:497

        ClassLoader contextCl = null;
        try {
            contextCl = Thread.currentThread().getContextClassLoader();
            Thread.currentThread().setContextClassLoader(cl);
            return Class.forName(className, false, cl);
        } catch (ClassNotFoundException e) {
            throw new ProgramInvocationException(
                    "The program's entry point class '"
                            + className
                            + "' was not found in the jar file.",
                    e);
        } catch (ExceptionInInitializerError e) {
            throw new ProgramInvocationException(
                    "The program's entry point class '"
                            + className
                            + "' threw an error during initialization.",
                    e);
        } catch (LinkageError e) {
            throw new ProgramInvocationException(
                    "The program's entry point class '"
                            + className
                            + "' could not be loaded due to a linkage failure.",
                    e);
        } catch (Throwable t) {
            throw new ProgramInvocationException(
                    "The program's entry point class '"
                            + className
                            + "' caused an exception during initialization: "
                            + t.getMessage(),
                    t);
        } finally {
            if (contextCl != null) {
                Thread.currentThread().setContextClassLoader(contextCl);
            }
        }
    }

View on GitHub (pinned to 2f3c205e92)

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).

Example fix

// before: NoClassDefFoundError for com.fasterxml.jackson.databind.ObjectMapper
// (dependency shaded out or missing)

// after: add to pom.xml or shade include
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
</dependency>

Defensive patterns

Strategy: try-catch

Try / catch

try {
    PackagedProgram.newBuilder()
        .setJarFile(jarFile)
        .setEntryPointClassName(className)
        .build();
} catch (ProgramInvocationException e) {
    if (e.getCause() instanceof LinkageError) {
        LinkageError le = (LinkageError) e.getCause();
        // inspect le for missing class / native lib / verify error
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/bdc8adf6121c851f. Report an issue: GitHub.