testcontainers/testcontainers-java · error · IllegalStateException

Failed to create directory at

Error message

Failed to create directory at: <directory>

What it means

PathUtils.mkdirp(Path) calls File.mkdirs() and throws IllegalStateException when it returns false. mkdirs() returns false only when the directory does not already exist AND could not be created (typically permission denied, or a parent is a regular file), since success or pre-existence both return true.

Solutions

1. Check that no parent path component is an existing regular file and remove/rename it
2. Grant write permission on the parent directory (chmod/chown) or run with sufficient privileges
3. Point the directory at a writable location (e.g. project target/ or java.io.tmpdir)
4. Ensure the directory doesn't already exist as a non-directory and the filesystem isn't read-only (mount -o rw)

Example fix

// before
PathUtils.mkdirp(Paths.get("/var/lib/myapp/state")); // may be unwritable
// after
Path dir = Paths.get(System.getProperty("java.io.tmpdir"), "myapp-state");
Files.createDirectories(dir); // clearer error, works with pre-existing dirs
PathUtils.mkdirp(dir);

Path dir = Paths.get("/some/state");
Path parent = dir.toAbsolutePath().getParent();
if (parent != null && Files.exists(parent) && !Files.isDirectory(parent))
    throw new IllegalStateException("Parent is a file: " + parent);
if (!Files.isWritable(parent))
    throw new IllegalStateException("No write permission on: " + parent);

boolean canCreate(Path dir) {
    Path p = dir.toAbsolutePath().getParent();
    return p != null && Files.isDirectory(p) && Files.isWritable(p);
}

try {
    PathUtils.mkdirp(dir);
} catch (IllegalStateException e) {
    Files.createDirectories(dir); // surfaces a precise java.nio reason (AccessDeniedException, etc.)
}

When it happens

Trigger: Calling PathUtils.mkdirp(new File("/some/path").toPath()) where the path's parent is a file, the user lacks write permission on the parent, or the filesystem is read-only. Used internally when Testcontainers prepares temp/Target dirs for container mounts.

Common situations: Mapping container paths into ./target on CI with restrictive umask; creating dirs under /var or C:\Program Files without elevation; a path component like 'target' actually being a file after a bad build; read-only Docker bind-mount roots.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Found docker unix domain socket but file mode was not as…
• Unable to read Dockerfile at path

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/cc04a6bcf171b749. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/utility/PathUtils.java:53

                    @Override
                    public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
                        Files.delete(file);
                        return FileVisitResult.CONTINUE;
                    }
                }
            );
        } catch (IOException ignored) {}
    }

    /**
     * Make a directory, plus any required parent directories.
     *
     * @param directory the directory path to make
     */
    public static void mkdirp(Path directory) {
        boolean result = directory.toFile().mkdirs();
        if (!result) {
            throw new IllegalStateException("Failed to create directory at: " + directory);
        }
    }

    /**
     * Create a MinGW compatible path based on usual Windows path
     *
     * @param path a usual windows path
     * @return a MinGW compatible path
     */
    public static String createMinGWPath(String path) {
        String mingwPath = path.replace('\\', '/');
        int driveLetterIndex = 1;
        if (mingwPath.matches("^[a-zA-Z]:\\/.*")) {
            driveLetterIndex = 0;
        }

        // drive-letter must be lower case
        mingwPath =

View on GitHub (pinned to 8e549514e3)