apache/flink · error · ProgramInvocationException

Invalid file path '{jarFile.getPath()}'

Error message

Invalid file path '{jarFile.getPath()}'

What it means

Thrown by getEntryPointClassNameFromJar when new File(jarFile.toURI()) raises URISyntaxException. The jar file URL cannot be converted to a valid URI/File, so the manifest cannot be read to discover the main class.

Source

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

            }
        } 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) {
            throw new ProgramInvocationException(
                    "Error while opening jar file '"
                            + jarFile.getPath()
                            + "'. "
                            + ioex.getMessage(),
                    ioex);
        }

        // jar file must be closed at the end
        try {
            // Read from jar manifest
            try {
                manifest = jar.getManifest();
            } catch (IOException ioex) {
                throw new ProgramInvocationException(
                        "The Manifest in the jar file could not be accessed '"

View on GitHub (pinned to 2f3c205e92)

Solutions

  1. Move/rename the jar to a path without spaces or special characters.
  2. Construct the jar URL via File.toURI().toURL() rather than string concatenation, ensuring proper escaping.
  3. Ensure the URL uses the 'file' scheme.
  4. On Windows, prefer forward-slash paths and avoid drive-letter edge cases.

Example fix

// before: manual string URL with a space
URL u = new URL("file:/C:/My Dir/job.jar"); // -> URISyntaxException in toURI()

// after: derive from File
URL u = new File("C:/My Dir/job.jar").toURI().toURL();
Defensive patterns

Strategy: validation

Validate before calling

// Validate the jar URL is a well-formed file URI before submission
try {
    URI u = jarFileUrl.toURI();
    if (!"file".equalsIgnoreCase(u.getScheme())) {
        throw new IllegalArgumentException("Jar URL is not a file: URI: " + u);
    }
    File f = new File(u);
    if (!f.isFile()) throw new IllegalArgumentException("Not a file: " + f);
} catch (URISyntaxException use) {
    throw new IllegalArgumentException("Invalid jar URI", use);
}

Try / catch

try {
    PackagedProgram.newBuilder().setJarFile(jarFile).build();
} catch (ProgramInvocationException pie) {
    if (pie.getMessage().startsWith("Invalid file path")) {
        // sanitize the path: remove spaces, rebuild URL from File
    }
    throw pie;
}

Prevention

When it happens

Trigger: The jarFile URL passed to getEntryPointClassNameFromJar contains characters that are illegal in a URI (unescaped spaces, special characters, or a non-file scheme that breaks toURI()).

Common situations: Job jar paths containing spaces or non-ASCII characters on Windows; jar URLs constructed manually with illegal syntax; a URL of a non-file scheme being passed where a file: URL is expected.

Related errors

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