What causes "Failed to create directory ${dir}" in quarkusio/quarkus?

Check whether a plain file exists at the target path and delete it before retrying

quarkusio/quarkus · error · IllegalStateException

Failed to create directory ${dir}

Error message

Failed to create directory ${dir}

What it means

IoUtils.failedToMkDir throws IllegalStateException when a directory could not be created on the filesystem. The library throws it from mkdir/mkdirs helpers (e.g. IoUtils.createTmpDir) when java.nio.file.Files.createDirectories fails silently (File.mkdir/mkdirs return false). It indicates a filesystem-level problem, not a programming error in most cases.

Source

Thrown at independent-projects/bootstrap/app-model/src/main/java/io/quarkus/bootstrap/util/IoUtils.java:39

import java.nio.file.attribute.BasicFileAttributes;
import java.util.EnumSet;
import java.util.Objects;
import java.util.UUID;

import org.jboss.logging.Logger;

/**
 *
 * @author Alexey Loubyansky
 */
public class IoUtils {

    private static final Path TMP_DIR = Paths.get(PropertyUtils.getProperty("java.io.tmpdir"));

    private static final Logger log = Logger.getLogger(IoUtils.class);

    private static void failedToMkDir(final Path dir) {
        throw new IllegalStateException("Failed to create directory " + dir);
    }

    public static Path createTmpDir(String name) {
        return mkdirs(TMP_DIR.resolve(name));
    }

    public static Path createRandomTmpDir() {
        return createTmpDir(UUID.randomUUID().toString());
    }

    public static Path createRandomDir(Path parentDir) {
        return mkdirs(parentDir.resolve(UUID.randomUUID().toString()));
    }

    public static Path mkdirs(Path dir) {
        try {
            Files.createDirectories(dir);
        } catch (IOException e) {

View on GitHub (pinned to e1c734241f)

Solutions

Check whether a plain file exists at the target path and delete it before retrying
Verify the process user has write permission on java.io.tmpdir (or the target parent directory)
Free disk space / check filesystem is not mounted read-only
Wrap the call and fall back to Files.createTempDirectory for a unique directory name

Example fix

// before
Path dir = IoUtils.createTmpDir("quarkus-build");
// after
Path base = Paths.get(System.getProperty("java.io.tmpdir"));
Path dir = Files.exists(base.resolve("quarkus-build"))
    ? base.resolve("quarkus-build")
    : IoUtils.createTmpDir("quarkus-build");

Defensive patterns

Strategy: validation

Validate before calling

Path dir = tmpDir.resolve(name);
if (Files.exists(dir) && !Files.isDirectory(dir))
    throw new IllegalStateException(dir + " exists as a file; remove it first");
if (!Files.isWritable(dir.getParent()))
    throw new IllegalStateException("No write permission on " + dir.getParent());

Try / catch

try {
    Path dir = IoUtils.createTmpDir("quarkus-build");
} catch (IllegalStateException e) {
    // fall back to a unique dir
    Path dir2 = Files.createTempDirectory("quarkus-build");
}

Prevention

Check java.io.tmpdir is writable for the user running the process
Clean stale temp files from crashed runs before reusing fixed directory names
Prefer Files.createTempDirectory for unique directories
Monitor disk space in CI/container environments

When it happens

Trigger: Calling IoUtils.createTmpDir(name) (which resolves a path under java.io.tmpdir and calls mkdirs) or IoUtils.mkdir(s)(path) when the directory already exists as a regular file, the parent is not writable, or the path exceeds the OS filename length limit.

Common situations: A stale file occupies the temp directory name from a previous crashed run; read-only temp disk or full disk; running in a container with an unwritable /tmp; permission changes after switching the user the process runs as.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/fa21932be4a8b700. Report an issue: GitHub.