apache/flink · critical · ProgramInvocationException

The program's entry point class '{className}' threw an error

Error message

The program's entry point class '{className}' threw an error during initialization.

What it means

Thrown when the entry point class's static initializer fails (ExceptionInInitializerError) during Class.forName. This means the class was found but its static {} block or static field initialization threw an exception. The original error is chained as the cause.

Source

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

            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(
                    "The program's entry point class '"
                            + className
                            + "' caused an exception during initialization: "
                            + t.getMessage(),
                    t);
        } finally {

View on GitHub (pinned to 2f3c205e92)

Solutions

Examine the chained ExceptionInInitializerError cause to find the original exception in the static initializer.
Move risky initialization logic out of static blocks into instance or main-method scope.
Ensure all system properties, env vars, and resources the static initializer depends on are available.
Run the jar locally with the same classpath to reproduce the initialization failure with a full stack trace.

Example fix

// before
public class JobMain {
    private static final Config CFG = Config.load("/etc/job.conf"); // throws if missing
}

// after
public class JobMain {
    private static Config cfg;
    public static void main(String[] args) {
        cfg = Config.load(System.getProperty("job.config", "/etc/job.conf"));
    }
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    PackagedProgram.newBuilder()
        .setJarFile(jarFile)
        .setEntryPointClassName(className)
        .build();
} catch (ProgramInvocationException e) {
    if (e.getCause() instanceof ExceptionInInitializerError) {
        Throwable initCause = e.getCause().getCause();
        // log and address the static initializer failure
    }
    throw e;
}

Prevention

Avoid heavy logic in static initializers of entry point classes.
Move resource/config loading into main() or instance init.
Test static initializers in isolation with the production classpath.

When it happens

Trigger: Loading a class whose static initializer performs an operation that fails: null dereference, failed config read, missing system property, static logger initialization failure, or a static field that calls a method which throws.

Common situations: Entry point class reads a system property or environment variable that is unset in deployment, static singleton initialization fails, or a static field references a resource that does not exist at class-load time.

Related errors

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