apache/flink · error · ProgramInvocationException

An error occurred while invoking the program's main method:

Error message

An error occurred while invoking the program's main method: {t.getMessage()}

What it means

Thrown by callMainMethod in the outer 'catch (Throwable t)' — a catch-all for any Throwable that is not IllegalArgumentException, IllegalAccessException, or InvocationTargetException. This catches Throwable-level errors raised during the Method.invoke call itself (not inside main), such as LinkageError, StackOverflowError, or ThreadDeath.

Source

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

                    "Could not invoke the main method, arguments are not matching.", e);
        } catch (IllegalAccessException e) {
            throw new ProgramInvocationException(
                    "Access to the main method was denied: " + e.getMessage(), e);
        } catch (InvocationTargetException e) {
            Throwable exceptionInMethod = e.getTargetException();
            if (exceptionInMethod instanceof Error) {
                throw (Error) exceptionInMethod;
            } else if (exceptionInMethod instanceof ProgramParametrizationException) {
                throw (ProgramParametrizationException) exceptionInMethod;
            } else if (exceptionInMethod instanceof ProgramInvocationException) {
                throw (ProgramInvocationException) exceptionInMethod;
            } else {
                throw new ProgramInvocationException(
                        "The main method caused an error: " + exceptionInMethod.getMessage(),
                        exceptionInMethod);
            }
        } catch (Throwable t) {
            throw new ProgramInvocationException(
                    "An error occurred while invoking the program's main method: " + t.getMessage(),
                    t);
        }
    }

    private static String getEntryPointClassNameFromJar(URL jarFile)
            throws ProgramInvocationException {
        JarFile jar;
        Manifest manifest;
        String className;

        // Open jar file
        try {
            jar = new JarFile(new File(jarFile.toURI()));
        } catch (URISyntaxException use) {
            throw new ProgramInvocationException(
                    "Invalid file path '" + jarFile.getPath() + "'", use);
        } catch (IOException ioex) {

View on GitHub (pinned to 2f3c205e92)

Solutions

Inspect the appended ': <message>' and the attached Throwable cause for the JVM-level error class.
Resolve dependency conflicts (use Flink's dependency-convergence check; shade conflicting transitive deps in the user jar).
Rebuild the user jar from a clean state to eliminate bytecode corruption.
If OutOfMemoryError/StackOverflowError, tune JVM heap/stack in flink-conf.yaml.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: check dependency convergence with Maven Enforcer before building the jar
// <plugin><artifactId>maven-enforcer-plugin</artifactId>
//   <executions><execution><id>enforce</id><goals><goal>enforce</goal></goals>
//     <configuration><rules><dependencyConvergence/></rules></configuration>
//   </execution></executions></plugin>

Try / catch

try {
    packagedProgram.invokeInteractiveModeForExecution();
} catch (ProgramInvocationException pie) {
    Throwable t = pie.getCause();
    if (t instanceof LinkageError) {
        // dependency conflict — inspect classpath, shade the conflicting lib
    }
    throw pie;
}

Prevention

Run maven-enforcer dependencyConvergence in the user jar build to catch version conflicts early.
Shade/transitive-reduce conflicting dependencies in the user jar.
Rebuild from clean to eliminate stale/corrupt bytecode.

When it happens

Trigger: Method.invoke raises a Throwable that bypasses the three specific exception catches — typically a LinkageError, ClassCircularityError, or other JVM/bytecode-level error.

Common situations: Corrupted or incompatible bytecode in the user jar; dependency version conflicts producing LinkageError/IncompatibleClassChangeError at invoke time; OutOfMemoryError during class initialization.

Related errors

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