What causes "Mkdirs failed to create {}" in apache/flink?

Pre-create the parent directory manually and verify writability: `mkdir -p `.

apache/flink · error · IOException

Mkdirs failed to create {}

Error message

Mkdirs failed to create {}

What it means

Thrown by LocalFileSystem.create() when mkdirs(parent) returns false — meaning parent directory creation was attempted but reported failure (without throwing). This typically indicates the parent could not be created due to permissions or a conflicting file.

Source

Thrown at flink-core/src/main/java/org/apache/flink/core/fs/local/LocalFileSystem.java:261

        } else {
            File parent = file.getParentFile();
            return (parent == null || mkdirsInternal(parent))
                    && (file.mkdir() || file.isDirectory());
        }
    }

    @Override
    public FSDataOutputStream create(final Path filePath, final WriteMode overwrite)
            throws IOException {
        checkNotNull(filePath, "filePath");

        if (exists(filePath) && overwrite == WriteMode.NO_OVERWRITE) {
            throw new FileAlreadyExistsException("File already exists: " + filePath);
        }

        final Path parent = filePath.getParent();
        if (parent != null && !mkdirs(parent)) {
            throw new IOException("Mkdirs failed to create " + parent);
        }

        final File file = pathToFile(filePath);
        return new LocalDataOutputStream(file);
    }

    @Override
    public boolean rename(final Path src, final Path dst) throws IOException {
        final File srcFile = pathToFile(src);
        final File dstFile = pathToFile(dst);

        final File dstParent = dstFile.getParentFile();

        // Files.move fails if the destination directory doesn't exist
        //noinspection ResultOfMethodCallIgnored -- we don't care if the directory existed or was
        // created
        dstParent.mkdirs();

View on GitHub (pinned to 2f3c205e92)

Solutions

Pre-create the parent directory manually and verify writability: `mkdir -p <parent>`.
Check and fix permissions on the parent path for the Flink user.
Ensure no regular file exists along the parent path.
Point the output to a writable, existing directory.

Defensive patterns

Strategy: validation

Validate before calling

void ensureParentWritable(Path filePath) throws IOException {
    java.io.File parent = new File(filePath.getParent().toUri());
    if (parent.exists() && !parent.isDirectory())
        throw new IOException("Parent is not a directory: " + parent);
    if (!parent.canWrite()) throw new IOException("Parent not writable: " + parent);
}

Try / catch

try {
    fs.create(p, mode);
} catch (IOException e) {
    if (e.getMessage().startsWith("Mkdirs failed to create")) {
        // fix perms / pre-create parent, then retry
    }
    throw e;
}

Prevention

Pre-create and chmod output parent directories.
Verify no file occupies any segment of the parent path.
Run jobs with users that have write access to the output root.

When it happens

Trigger: Calling create(filePath) where filePath.getParent() is non-null and mkdirs(parent) returns false rather than throwing.

Common situations: Insufficient permissions to create the parent directory chain; a file already exists somewhere in the parent path; read-only mount; parent path on a volume that is full or read-only.

Related errors

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