eclipse-vertx/vert.x · error · IllegalStateException

create

Error message

create

What it means

Wrap of an IOException raised while creating the file cache directory in FileCache.setupCacheDir. The message 'create' is the failing operation label; the actual cause (permissions, disk full, invalid path) is in the exception's cause chain.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileCache.java:66

      cacheDirName = findUniqueDir(fileCacheDir);
    } else {
      // the cacheDir will be suffixed a unique id to avoid eavesdropping from other processes/users
      // also this ensures that if process A deletes cacheDir, it won't affect process B
      cacheDirName = fileCacheDir + "-" + UUID.randomUUID();
    }
    File cacheDir = new File(cacheDirName);
    // Create the cache directory
    try {
      if (Utils.isWindows()) {
        Files.createDirectories(cacheDir.toPath());
      } else {
        // for security reasons, cache directory should not be readable/writable from other users
        // just like "POSIX mkdtemp(3)", the created directory should have 0700 permission
        Set<PosixFilePermission> perms = PosixFilePermissions.fromString("rwx------");
        Files.createDirectories(cacheDir.toPath(), PosixFilePermissions.asFileAttribute(perms));
      }
    } catch (IOException e) {
      throw new IllegalStateException(FileSystemImpl.getFolderAccessErrorMessage("create", fileCacheDir), e);
    }
    return cacheDir;
  }

  /**
   * Find a unique directory path. If the base path doesn't exist, return it.
   * If it exists, append "-2", "-3", etc. until a non-existing path is found.
   */
  private static String findUniqueDir(String basePath) {
    File baseDir = new File(basePath);
    if (!baseDir.exists()) {
      return basePath;
    }
    // Directory exists, find a unique suffix
    int suffix = 2;
    while (true) {
      String candidatePath = basePath + "-" + suffix;
      File candidate = new File(candidatePath);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the cause for the real filesystem error
2. Verify write permission on the configured file cache directory (vertx.cacheDirBase)
3. Free disk space or choose another cache location

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileCache.java:66 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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