elastic/elasticsearch · error · UncheckedIOException

Cannot create directory '%s' as it already exists, but is no

Error message

Cannot create directory '%s' as it already exists, but is not a directory

What it means

FileUtils.mkdirs() throws if `dir.exists()` is true BUT `dir.isDirectory()` is false — i.e. a regular file (or special file) already occupies the path where a directory is requested. This is the 'path collision' guard: mkdirs would otherwise fail opaquely or, worse, mask the conflict. It is NOT thrown when the path doesn't exist (that's the create path) or when it's already a directory (early return).

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/util/FileUtils.java:34

import java.util.Collections;
import java.util.LinkedList;
import java.util.List;

public final class FileUtils {

    /**
     * Like {@link java.io.File#mkdirs()}, except throws an informative error if a dir cannot be created.
     *
     * @param dir The dir to create, including any non existent parent dirs.
     */
    public static void mkdirs(File dir) {
        dir = dir.getAbsoluteFile();
        if (dir.isDirectory()) {
            return;
        }

        if (dir.exists() && dir.isDirectory() == false) {
            throw new UncheckedIOException(String.format("Cannot create directory '%s' as it already exists, but is not a directory", dir));
        }

        List<File> toCreate = new LinkedList<File>();
        File parent = dir.getParentFile();
        while (parent.exists() == false) {
            toCreate.add(parent);
            parent = parent.getParentFile();
        }
        Collections.reverse(toCreate);
        for (File parentDirToCreate : toCreate) {
            if (parentDirToCreate.isDirectory()) {
                continue;
            }
            File parentDirToCreateParent = parentDirToCreate.getParentFile();
            if (parentDirToCreateParent.isDirectory() == false) {
                throw new UncheckedIOException(
                    String.format(
                        "Cannot create parent directory '%s' when creating directory '%s' as '%s' is not a directory",

View on GitHub (pinned to db6a809a66)

Solutions

Identify and remove/redirect the conflicting file: `ls -la <path>` to see what it is.
If it's a stale artifact, delete it and rerun (or run `./gradlew clean`).
If a symlink, point it at a directory or remove it.
Restructure so the same path isn't used as both a file and a directory across tasks.

Example fix

# before: a file exists at build/output
rm build/output   # the conflicting file
# now mkdirs will succeed
FileUtils.mkdirs(file('build/output'))

Defensive patterns

Strategy: validation

Validate before calling

if (dir.exists() && !dir.isDirectory()) {
  throw new UncheckedIOException(
    "Path " + dir + " is a non-directory file; remove it before mkdirs.");
}

Prevention

Use distinct base paths for generated files vs generated directories.
Run `./gradlew clean` between incompatible build shapes to clear stray files.
Avoid symlinks-to-files inside the build tree where directories are expected.

When it happens

Trigger: Calling `FileUtils.mkdirs(file)` where `file` points at an existing non-directory: a previously-created file, a symlink to a file, a socket/device, or a broken symlink that `exists()` resolves as present.

Common situations: A build step created a file (e.g. a marker or lock) at a path later treated as a directory; a symlink in the build dir points at a file; a previous run left a stray file; cross-platform path handling where Windows considers some paths files.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/6b0be96451bd7cca. Report an issue: GitHub.