apache/flink · warning · ProgramInvocationException

Error while getting the program description

Error message

Error while getting the program description

What it means

Thrown by PackagedProgram.getJobDescription() when the entry class implements ProgramDescription but its getDescription() call raised a Throwable. Note the silent null return when instantiation fails (catch-all returning null above); this exception is only for failures inside getDescription() itself.

Source

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

     */
    @Nullable
    public String getDescription() throws ProgramInvocationException {
        if (ProgramDescription.class.isAssignableFrom(this.mainClass)) {

            ProgramDescription descr;
            try {
                descr =
                        InstantiationUtil.instantiate(
                                this.mainClass.asSubclass(ProgramDescription.class),
                                ProgramDescription.class);
            } catch (Throwable t) {
                return null;
            }

            try {
                return descr.getDescription();
            } catch (Throwable t) {
                throw new ProgramInvocationException(
                        "Error while getting the program description"
                                + (t.getMessage() == null ? "." : ": " + t.getMessage()),
                        t);
            }

        } else {
            return null;
        }
    }

    /**
     * This method assumes that the context environment is prepared, or the execution will be a
     * local execution by default.
     */
    public void invokeInteractiveModeForExecution() throws ProgramInvocationException {
        FlinkSecurityManager.monitorUserSystemExitForCurrentThread();
        try {
            callMainMethod(mainClass, args);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Make getDescription() a pure, dependency-light method that returns a string without touching files or external state.
2. Ensure any resources/files read by getDescription() are packaged inside the job jar.
3. If the description is not needed, remove the ProgramDescription interface from the class so getJobDescription() silently returns null instead of failing.
4. Inspect the appended ': <message>' in the exception to find the root cause thrown by getDescription().

Example fix

// before
@Override
public String getDescription() {
    return Files.readString(Path.of("/etc/flink/job-desc.txt")); // throws if missing
}

// after
@Override
public String getDescription() {
    return "Fraud detection streaming job v2";
}

// If you implement ProgramDescription, unit-test getDescription() in isolation
ProgramDescription pd = (ProgramDescription) mainClass.getDeclaredConstructor().newInstance();
String d = pd.getDescription(); // fails fast in tests, not at runtime
assert d != null && !d.isEmpty();

String desc;
try {
    desc = packagedProgram.getJobDescription(); // may throw ProgramInvocationException
} catch (ProgramInvocationException pie) {
    desc = packagedProgram.getClass().getName(); // fallback description
    log.warn("Could not obtain program description, using class name", pie);
}

When it happens

Trigger: The user's main class implements org.apache.flink.api.common.ProgramDescription, the instance was created successfully, but invoking getDescription() on it throws. Common: getDescription() reads a resource/config that is missing, or it contains a bug.

Common situations: Custom job classes that implement ProgramDescription to provide a description for the web UI / plan visualization, but whose getDescription() relies on resources not packaged into the jar.

Related errors

• The Manifest in the jar file could not be accessed '{jarFile
• No manifest found in jar file '{jarFile.getPath()}'. The man
• Neither a '{MANIFEST_ATTRIBUTE_MAIN_CLASS}', nor a '{MANIFES
• The given program class does not have a main(String[]) metho
• URL is invalid. This should not happen.

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