apache/flink · error · RuntimeException

Could not create a valid URI from the given file path name:

Error message

Could not create a valid URI from the given file path name: {}

What it means

When setFilePath(String) constructs a new Path(filePath), the Path constructor can throw a RuntimeException (e.g. from URI parsing) if the string is malformed — missing scheme, illegal characters, unencodable segments. FileInputFormat catches that and rethrows as a RuntimeException with a clearer message indicating the path could not be turned into a valid URI.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/io/FileInputFormat.java:272

        if (filePath == null) {
            throw new IllegalArgumentException("File path cannot be null.");
        }

        // TODO The job-submission web interface passes empty args (and thus empty
        // paths) to compute the preview graph. The following is a workaround for
        // this situation and we should fix this.

        // comment (Stephan Ewen) this should be no longer relevant with the current Java/Scala
        // APIs.
        if (filePath.isEmpty()) {
            setFilePath(new Path());
            return;
        }

        try {
            this.setFilePath(new Path(filePath));
        } catch (RuntimeException rex) {
            throw new RuntimeException(
                    "Could not create a valid URI from the given file path name: "
                            + rex.getMessage());
        }
    }

    /**
     * Sets a single path of a file to be read.
     *
     * @param filePath The path of the file to read.
     */
    public void setFilePath(Path filePath) {
        if (filePath == null) {
            throw new IllegalArgumentException("File path must not be null.");
        }

        setFilePaths(filePath);
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Use a fully-qualified, properly-encoded URI (e.g. 'hdfs:///data/input' or 'file:///abs/path').
2. Percent-encode spaces and special characters, or use the Path(URI) overload.
3. Construct the Path yourself with new Path(scheme, authority, path) and pass it to setFilePath(Path) to control parsing.
4. On local files use absolute paths under a 'file://' scheme.

Example fix

// before
format.setFilePath("C:\\data\\input file.csv"); // backslashes + space -> throws

// after
format.setFilePath("file:///C:/data/input%20file.csv");
// or build a Path explicitly
format.setFilePath(new Path("file", "", "/C:/data/input file.csv"));

// Pre-validate by constructing the Path and catching issues with a clearer message.
Path p;
try {
    p = new Path(pathString);
} catch (RuntimeException e) {
    throw new IllegalArgumentException("Invalid file path URI: " + pathString, e);
}
format.setFilePath(p);

try {
    format.setFilePath(pathString);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("valid URI")) {
        // log the offending path, suggest encoding, rethrow with context
        throw new IllegalArgumentException("Cannot parse path '" + pathString + "'; use a fully-qualified, encoded URI", e);
    }
    throw e;
}

When it happens

Trigger: Passing a path string with illegal URI characters (spaces, unencoded special chars), a missing/misspelled scheme (e.g. 'hdfs:/data' with a single slash), or a relative path that the URI parser rejects.

Common situations: Windows paths with backslashes or drive letters; paths with spaces not percent-encoded; copy-pasting an S3/HDFS URL missing a slash; mixing local and distributed path styles.

Related errors

• Error: Invalid number of samples: ${numSamples}
• File path cannot be null.
• File path must not be null.
• At least one file path must be specified.
• File path was not specified in input format or configuration

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