halo-dev/halo · warning · DirectoryNotEmptyException

Target directory: {path} was not empty

Error message

Target directory: {path} was not empty

What it means

Thrown as java.nio.file.DirectoryNotEmptyException by FileUtils.ensureEmpty when the given Path is a non-empty directory. Callers use ensureEmpty to assert a target is clear before writing into it (e.g. extraction/cleanup targets).

Source

Thrown at application/src/main/java/run/halo/app/infra/utils/FileUtils.java:172

        Assert.notNull(path, "Path must not be null");

        if (Files.notExists(path)) {
            // Create directories
            Files.createDirectories(path);

            log.debug("Created directory: [{}]", path);
        }
    }

    /**
     * The given path must be empty.
     *
     * @param path path must not be null
     * @throws IOException io exception
     */
    public static void ensureEmpty(Path path) throws IOException {
        if (!isEmpty(path)) {
            throw new DirectoryNotEmptyException("Target directory: " + path + " was not empty");
        }
    }

    /**
     * Checks if the given path is empty.
     *
     * @param path path must not be null
     * @return true if the given path is empty; false otherwise
     * @throws IOException io exception
     */
    public static boolean isEmpty(Path path) throws IOException {
        Assert.notNull(path, "Path must not be null");

        if (!Files.isDirectory(path) || Files.notExists(path)) {
            return true;
        }

        try (Stream<Path> pathStream = Files.list(path)) {

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Clear the directory contents (or delete and recreate it) before calling ensureEmpty.
2. Point the path at the intended empty target.
3. If partial contents are expected, switch to a cleanup step instead of asserting emptiness.
4. Check for hidden/lock files and remove them.

Example fix

// before
FileUtils.ensureEmpty(dataDir); // throws

// after
FileUtils.deleteRecursively(dataDir);
Files.createDirectories(dataDir);
FileUtils.ensureEmpty(dataDir);

if (!FileUtils.isEmpty(path)) {
    // decide: clean it or pick another target
    Files.list(path).forEach(p -> { try { Files.deleteIfExists(p); } catch (IOException ignored) {} });
}

static boolean pathIsEmpty(Path p) throws IOException {
    return Files.notExists(p) || (Files.isDirectory(p) && Files.list(p).findAny().isEmpty());
}

try {
    FileUtils.ensureEmpty(target);
} catch (DirectoryNotEmptyException e) {
    // either clean and retry or report to the user
    FileUtils.deleteRecursively(target);
    Files.createDirectories(target);
}

When it happens

Trigger: Calling FileUtils.ensureEmpty(path) on a directory that contains any entries (files or subdirectories), including hidden files.

Common situations: Re-running setup into a previously populated data dir; leftover temp files from a crashed run; hidden files (.DS_Store, lock files) blocking an 'empty' check; pointing at the wrong directory.

Related errors

• Host runtime snapshot packages must be an object.
• problemDetail.directoryTraversal
• Failed to unzip theme

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/de1c199bcf69e4fa. Report an issue: GitHub.