apache/flink · error · ProgramInvocationException

The main method caused an error: {exceptionInMethod.getMessa

Error message

The main method caused an error: {exceptionInMethod.getMessage()}

What it means

Thrown by callMainMethod when Method.invoke raises InvocationTargetException and the unwrapped target exception is NOT an Error, ProgramParametrizationException, or ProgramInvocationException (those are rethrown directly). This is the general case: the user's main method threw an application exception.

Source

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

        try {
            mainMethod.invoke(null, (Object) args);
        } catch (IllegalArgumentException e) {
            throw new ProgramInvocationException(
                    "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 {

View on GitHub (pinned to 2f3c205e92)

Solutions

Read the appended ': <message>' and inspect the attached cause Throwable for the root exception in the user program.
Fix the underlying bug in the user main method and resubmit.
If the error originates from Flink setup (e.g. StreamExecutionEnvironment), verify configuration and environment before the execute() call.
Add proper argument parsing/validation in main so config errors surface as ProgramParametrizationException (which is handled distinctly).

Example fix

// before: bare throw leaks as generic InvocationTargetException
public static void main(String[] args) throws Exception {
    var env = StreamExecutionEnvironment.getExecutionEnvironment();
    env.execute(); // throws on bad config
}

// after: catch and rethrow with clear context
public static void main(String[] args) throws Exception {
    try { ... }
    catch (ParameterException pe) {
        throw new ProgramParametrizationException(pe.getMessage()); // distinct handling
    }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Wrap the body of main in try/catch and convert known config errors to
// ProgramParametrizationException so they surface distinctly (not as generic errors).

Try / catch

try {
    packagedProgram.invokeInteractiveModeForExecution();
} catch (ProgramInvocationException pie) {
    Throwable userCause = pie.getCause(); // the original exception from main
    log.error("User main failed: {}", userCause.getMessage(), userCause);
    // surface userCause to the operator with full stacktrace
}

Prevention

Validate program arguments early and throw ProgramParametrizationException for usage errors (handled distinctly).
Wrap risky setup (env creation, source connection) in try/catch inside main with descriptive messages.
Log the full cause stacktrace; the message alone is often insufficient.

When it happens

Trigger: The submitted program's main method throws any Exception (or Throwable not matching the special cases). The original exception is attached as the cause.

Common situations: Any user-code bug inside main: NPE, illegal config value, failed connection to Kafka/source, parse error on args, uncaught exception in the job graph construction.

Related errors

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