eclipse-vertx/vert.x · error · FileSystemException

Failed to delete ${path}

Error message

Failed to delete ${path}

What it means

Thrown when FileSystem.delete / deleteRecursive fails: Vert.x resolves the path and deletes it (recursively if requested), wrapping any IOException into a FileSystemException via getFileAccessErrorMessage("delete", path) — 'Failed to delete <path>'. It indicates the OS refused or could not complete the deletion.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileSystemImpl.java:676

          throw new FileSystemException(getFileAccessErrorMessage("read", link), e);
        }
      }
    };
  }

  private BlockingAction<Void> deleteInternal(String path) {
    return deleteInternal(path, false);
  }

  private BlockingAction<Void> deleteInternal(String path, boolean recursive) {
    Objects.requireNonNull(path);
    return new BlockingAction<Void>() {
      public Void perform() {
        try {
          Path source = resolveFile(path).toPath();
          delete(source, recursive);
        } catch (IOException e) {
          throw new FileSystemException(getFileAccessErrorMessage("delete", path), e);
        }
        return null;
      }
    };
  }

  public static void delete(Path path, boolean recursive) throws IOException {
    if (recursive) {
      Files.walkFileTree(path, new SimpleFileVisitor<Path>() {
        public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
          Files.delete(file);
          return FileVisitResult.CONTINUE;
        }
        public FileVisitResult postVisitDirectory(Path dir, IOException e) throws IOException {
          if (e == null) {
            Files.delete(dir);
            return FileVisitResult.CONTINUE;
          } else {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass recursive=true when deleting a non-empty directory.
2. Ensure the process has write+execute permission on the parent directory and, for recursive deletes, on all children.
3. Close all open files/streams before deleting (especially on Windows).
4. Check getCause() for DirectoryNotEmptyException vs AccessDeniedException to pick the right fix.

Example fix

// before
vertx.fileSystem().deleteBlocking("/tmp/cache"); // DirectoryNotEmptyException
// after
vertx.fileSystem().delete("/tmp/cache", true);

FileSystem fs = vertx.fileSystem();
if (fs.existsBlocking(path) && fs.propsBlocking(path).isDirectory() && fs.readDirBlocking(path).size() > 0 && !recursive) throw new IllegalStateException("directory not empty: " + path);

try { vertx.fileSystem().deleteBlocking(path); } catch (FileSystemException e) { if (e.getCause() instanceof DirectoryNotEmptyException) { vertx.fileSystem().deleteBlockingRecursive(path); } else throw e; }

When it happens

Trigger: vertx.fileSystem().delete(path, recursive) on a non-empty directory with recursive=false (DirectoryNotEmptyException), missing write permission on the parent directory, files locked/open on Windows, or a missing path.

Common situations: Deleting a temp/cache directory that still has children; cleanup code on Windows while files are memory-mapped or open; read-only container layers; NFS 'stale file handle' during recursive deletes.

Related errors

• Failed to create ${path}
• Cannot read directory ${file}. Does not exist
• Cannot read directory ${file}. It's not a directory
• Failed to read ${p}
• Failed to chmod ${path}

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/77be6d2021c66b42. Report an issue: GitHub.