apache/flink · error · IllegalArgumentException

Can not create a Path from an empty string

Error message

Can not create a Path from an empty string

What it means

Thrown by Path's private checkPathArg when constructing a Path from a String whose length is zero. The Path constructor treats path strings as URIs and an empty URI has no meaning, so it is rejected before any parsing. A separate message exists for null inputs.

Source

Thrown at flink-core/src/main/java/org/apache/flink/core/fs/Path.java:163

        final URI resolved = parentUri.resolve(child.uri);
        initialize(resolved.getScheme(), resolved.getAuthority(), resolved.getPath());
    }

    /**
     * Checks if the provided path string is either null or has zero length and throws a {@link
     * IllegalArgumentException} if any of the two conditions apply.
     *
     * @param path the path string to be checked
     * @return The checked path.
     */
    private String checkPathArg(String path) {
        // disallow construction of a Path from an empty string
        if (path == null) {
            throw new IllegalArgumentException("Can not create a Path from a null string");
        }
        if (path.length() == 0) {
            throw new IllegalArgumentException("Can not create a Path from an empty string");
        }
        return path;
    }

    /**
     * Construct a path from a String. Path strings are URIs, but with unescaped elements and some
     * additional normalization.
     *
     * @param pathString the string to construct a path from
     */
    public Path(String pathString) {
        pathString = checkPathArg(pathString);

        // We can't use 'new URI(String)' directly, since it assumes things are
        // escaped, which we don't require of Paths.

        // add a slash in front of paths with Windows drive letters
        if (hasWindowsDrive(pathString, false)) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Validate the path string is non-empty before constructing the Path: `if (pathStr == null || pathStr.isEmpty()) throw ...`.
2. Check the config option supplying the path (e.g. `state.checkpoints.dir`, `fs.default-scheme`) and ensure it has a real value.
3. If the path may legitimately be unset, supply a sensible default or skip the operation rather than passing "".
4. Add a startup assertion in your job main() that resolves all configured paths to non-empty strings.

Example fix

// before
Path p = new Path(config.get("output.dir"));

// after
String dir = config.get("output.dir");
if (dir == null || dir.isEmpty()) {
    throw new IllegalArgumentException("output.dir must be configured");
}
Path p = new Path(dir);

private static Path safePath(String s) {
    if (s == null) throw new IllegalArgumentException("path is null");
    String trimmed = s.trim();
    if (trimmed.isEmpty()) throw new IllegalArgumentException("path is empty");
    return new Path(trimmed);
}

When it happens

Trigger: Calling `new Path("")` or any Path factory (Path(String), Path(URI) indirectly) that resolves to an empty string. Also reached when a config option, connector path, or checkpoint/savepoint location string trims to empty and is passed into a Path.

Common situations: A misconfigured `state.checkpoints.dir` or `execution.checkpointing.savepoint` set to an empty value; a dynamically-built path whose variable substitution failed (e.g. ENV var unset yielding ""); a unit test passing an empty literal.

Related errors

• tempDirectories contains null entries
• {directory} is not a directory but a regular file
• The directory %s dose not exist.
• The %s is not a directory.
• Not allowed configuration change(s) were detected:\n - {erro

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