apache/flink · error · IOException

JAR file path is invalid '{}'

Error message

JAR file path is invalid '{}'

What it means

JarUtils.checkJarFile converts the given jar URL to a File via jar.toURI(). A URISyntaxException here means the URL is not a valid URI — it cannot even be converted to a filesystem path, so validation stops with this IOException naming the offending URL.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/JarUtils.java:43

import java.net.MalformedURLException;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.jar.JarFile;
import java.util.stream.Collectors;

/** Utility functions for jar files. */
@Internal
public class JarUtils {

    public static void checkJarFile(URL jar) throws IOException {
        File jarFile;
        try {
            jarFile = new File(jar.toURI());
        } catch (URISyntaxException e) {
            throw new IOException("JAR file path is invalid '" + jar + '\'');
        }
        if (!jarFile.exists()) {
            throw new IOException("JAR file does not exist '" + jarFile.getAbsolutePath() + '\'');
        }
        if (!jarFile.canRead()) {
            throw new IOException("JAR file can't be read '" + jarFile.getAbsolutePath() + '\'');
        }

        try (JarFile ignored = new JarFile(jarFile)) {
            // verify that we can open the Jar file
        } catch (IOException e) {
            throw new IOException(
                    "Error while opening jar file '" + jarFile.getAbsolutePath() + '\'', e);
        }
    }

    public static List<URL> getJarFiles(final String[] jars) {
        if (jars == null) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Encode the path properly: build the URL with new File(path).toURI().toURL() instead of string concatenation.
2. Move or reference the jar from a path without spaces or special characters.
3. URL-encode problematic characters in the path (space -> %20) if the URL must be constructed manually.
4. Print the URL from the error message and validate it with new URI(url) to spot the syntax problem.

Example fix

// before
URL jarUrl = new URL("file:" + jarPath); // breaks when jarPath has spaces

// after
URL jarUrl = new File(jarPath).toURI().toURL();

// Build the URL from a File so URI encoding is always valid
URL jarUrl = new File(jarPath).getAbsoluteFile().toURI().toURL();
JarUtils.checkJarFile(jarUrl);

try {
    JarUtils.checkJarFile(jar);
} catch (IOException e) {
    if (e.getMessage().startsWith("JAR file path is invalid")) {
        // re-encode the path via File.toURI().toURL() and retry once
    }
}

When it happens

Trigger: Calling JarUtils.checkJarFile(url) with a URL whose URI form is syntactically invalid — e.g. a URL containing unencoded spaces, brackets, or a double slash produced by string concatenation instead of a proper URL/URI constructor.

Common situations: A jar path with spaces or special characters in directories like 'C:/Program Files/...' passed unencoded; building a jar URL by concatenating strings ('file:' + path) instead of File.toURI().toURL(); misconfigured pipeline.jars / -C classpath entries on the command line.

Related errors

• JAR file path invalid
• Problem with jar file {}
• Bad syntax for classpath: {}
• Multiple compatible client factories found for: {}.
• No ClusterClientFactory found. If you were targeting a Yarn

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