elastic/elasticsearch · error · UncheckedIOException

Failed to create parent directory '%s' when creating directo

Error message

Failed to create parent directory '%s' when creating directory '%s'

What it means

FileUtils.mkdirs() throws when an intermediate parent directory's `mkdir()` returns false AND a follow-up `isDirectory()` still returns false — i.e. the OS refused to create the directory and it isn't already there (the `&&` re-check handles races where another process created it). Distinct from #117 (ancestor is a file) and #119 (the final dir itself fails).

Source

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

        }
        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",
                        parentDirToCreate,
                        dir,
                        parentDirToCreateParent
                    )
                );
            }
            if (parentDirToCreate.mkdir() == false && parentDirToCreate.isDirectory() == false) {
                throw new UncheckedIOException(
                    String.format("Failed to create parent directory '%s' when creating directory '%s'", parentDirToCreate, dir)
                );
            }
        }
        if (dir.mkdir() == false && dir.isDirectory() == false) {
            throw new UncheckedIOException(String.format("Failed to create directory '%s'", dir));
        }
    }

    public static String read(File file, String encoding) {
        try {
            return org.apache.commons.io.FileUtils.readFileToString(file, encoding);
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }

    public static List<String> readLines(File file, String encoding) {

View on GitHub (pinned to db6a809a66)

Solutions

Check permissions on the immediate parent of the failing directory (`ls -la <parent>`) and grant write access.
Verify the filesystem is mounted read-write (`mount | grep <path>`).
Clear disk quota issues (`quota -u <user>`) or free inodes (`df -i`).
If sandboxed (container/CI), ensure the build dir is on a writable volume.

Defensive patterns

Strategy: try-catch

Validate before calling

File parent = dir.getParentFile();
if (parent != null && parent.exists() && !parent.canWrite()) {
  throw new IllegalStateException("No write permission on " + parent + " for mkdirs");
}

Try / catch

try {
  FileUtils.mkdirs(dir);
} catch (UncheckedIOException e) {
  if (e.getMessage().contains("Failed to create parent directory")) {
    // verify permissions / read-only mount / quota, then remediate and retry
  }
  throw e;
}

Prevention

Ensure the build directory and its ancestors are writable by the build user.
On CI/container hosts, mount the build volume read-write with adequate quota.
Check `df -h` / `df -i` and `mount` before large builds.

When it happens

Trigger: Permissions denied on the parent of a directory to create; read-only filesystem; quota exceeded; a different process holds an exclusive lock; the path component has an illegal name. The parent-of-parent IS a valid directory (passed the #117 check) but creating the child still fails.

Common situations: Build running as a user without write permission to the build root; read-only mount (some container/CI sandboxes); disk quota hit; SELinux/AppArmor denying the create; path too long on Windows.

Related errors

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