apache/flink · error · CliArgsException

Bad syntax for classpath: {}

Error message

Bad syntax for classpath: {}

What it means

Thrown by ProgramOptions constructor when parsing the --classpath (-c) option values. Each classpath entry is passed to `new URL(path)`, and if the path string is not a valid URL (missing protocol, malformed characters), MalformedURLException is caught and re-thrown as CliArgsException. Flink requires fully-qualified URL syntax for classpath entries (file://, http://, etc.).

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/cli/ProgramOptions.java:91

        this.entryPointClass =
                line.hasOption(CLASS_OPTION.getOpt())
                        ? line.getOptionValue(CLASS_OPTION.getOpt())
                        : null;

        this.jarFilePath =
                line.hasOption(JAR_OPTION.getOpt())
                        ? line.getOptionValue(JAR_OPTION.getOpt())
                        : null;

        this.programArgs = extractProgramArgs(line);

        List<URL> classpaths = new ArrayList<URL>();
        if (line.hasOption(CLASSPATH_OPTION.getOpt())) {
            for (String path : line.getOptionValues(CLASSPATH_OPTION.getOpt())) {
                try {
                    classpaths.add(new URL(path));
                } catch (MalformedURLException e) {
                    throw new CliArgsException("Bad syntax for classpath: " + path);
                }
            }
        }
        this.classpaths = classpaths;

        if (line.hasOption(PARALLELISM_OPTION.getOpt())) {
            hasParallelismOpt = true;
            String parString = line.getOptionValue(PARALLELISM_OPTION.getOpt());
            try {
                parallelism = Integer.parseInt(parString);
                if (parallelism <= 0 && parallelism != ExecutionConfig.PARALLELISM_DEFAULT) {
                    throw new NumberFormatException();
                }
            } catch (NumberFormatException e) {
                throw new CliArgsException(
                        "The parallelism must be a positive number: " + parString);
            }
        } else {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Prefix filesystem paths with file:// protocol, e.g. `-c file:///opt/libs/mylib.jar`
2. Use absolute paths with proper URL encoding (replace spaces with %20)
3. Pass each classpath entry as a separate -c argument

Example fix

// before
flink run -c /opt/libs/mylib.jar ./job.jar

// after
flink run -c file:///opt/libs/mylib.jar ./job.jar

for (String path : classpathEntries) {
    try {
        new URL(path);
    } catch (MalformedURLException e) {
        // auto-fix bare paths
        String fixed = path.startsWith("file:") ? path : "file://" + new File(path).getAbsolutePath();
        urls.add(new URL(fixed));
    }
}

When it happens

Trigger: Passing a bare filesystem path like `/opt/libs/mylib.jar` instead of `file:///opt/libs/mylib.jar`; using a relative path; malformed URL with illegal characters or unencoded spaces.

Common situations: User accustomed to colon-separated classpaths (like Java's -cp) passes `lib/a.jar:lib/b.jar` which is not valid URL syntax; spaces in paths that aren't URL-encoded; mixing forward/backward slashes on Windows.

Related errors

• The parallelism must be a positive number: {}
• No cluster id was specified. Please specify a cluster to whi
• The configuration directory '{}', specified in the '{}' envi
• The configuration directory was not specified. Please specif
• No valid command-line found.

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