apache/flink · error · ProgramInvocationException

The program's entry point class '{className}' was not found

Error message

The program's entry point class '{className}' was not found in the jar file.

What it means

Thrown when Class.forName(className, false, cl) raises a ClassNotFoundException while loading the entry point (main) class of a user jar. The class name was specified but is not present in the jar or any of the libraries on the provided ClassLoader. This is a ProgramInvocationException wrapping the original ClassNotFoundException.

Source

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

            }

            checkJarFile(jarFileUrl);

            return jarFileUrl;
        } else {
            return null;
        }
    }

    private static Class<?> loadMainClass(String className, ClassLoader cl)
            throws ProgramInvocationException {
        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(

View on GitHub (pinned to 2f3c205e92)

Solutions

Verify the entry point class name matches a class inside the jar (inspect with 'jar tf your.jar | grep ClassName').
If using a thin jar, rebuild as a fat/uber jar so all dependencies are included.
Check that setEntryPointClassName uses the fully qualified name with correct package.
Ensure any required user-classpath libraries are added via setUserClassPaths.

Example fix

// before
PackagedProgram.newBuilder()
    .setJarFile(jarFile)
    .setEntryPointClassName("com.example.Main")  // not in jar
    .build();

// after
PackagedProgram.newBuilder()
    .setJarFile(jarFile)
    .setEntryPointClassName("com.example.JobMain")  // correct FQN
    .build();

Defensive patterns

Strategy: validation

Validate before calling

try (JarFile jar = new JarFile(jarFile)) {
    String entry = className.replace('.', '/') + ".class";
    if (jar.getJarEntry(entry) == null) {
        throw new IllegalStateException("Class not found in jar: " + className);
    }
}

Try / catch

try {
    PackagedProgram.newBuilder()
        .setJarFile(jarFile)
        .setEntryPointClassName(className)
        .build();
} catch (ProgramInvocationException e) {
    if (e.getMessage().contains("was not found in the jar file")) {
        // class missing — fix class name or rebuild jar
    }
    throw e;
}

Prevention

Verify the entry point class exists in the jar with 'jar tf' before deployment.
Use fully qualified class names matching the package structure.
Build fat jars to avoid missing transitive dependencies.

When it happens

Trigger: Calling PackagedProgram.newBuilder().setEntryPointClassName(className).build() or setJarFile + setEntryPointClassName where the named class does not exist in the jar or its embedded/attached libraries. Also triggered when a fat jar is missing shaded dependencies.

Common situations: Wrong main class name (typo, wrong package), jar built without bundling dependencies (thin jar), entry class in a dependency that was not packaged, or class name from manifest pointing to a relocated/shaded class.

Related errors

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