eclipse-vertx/vert.x · error · VertxException

Cannot get canonical name of cacheDir

Error message

Cannot get canonical name of cacheDir

What it means

Construction failure in the FileCache constructor: File.getCanonicalFile() threw an IOException, so the cache directory's canonical path could not be resolved (typically an I/O error or unresolvable path). The VertxException wraps the original cause; the input at fault is the cacheDir File passed in.

Source

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

    int suffix = 2;
    while (true) {
      String candidatePath = basePath + "-" + suffix;
      File candidate = new File(candidatePath);
      if (!candidate.exists()) {
        return candidatePath;
      }
      suffix++;
    }
  }

  private Thread shutdownHook;
  private File cacheDir;

  public FileCache(File cacheDir) {
    try {
      this.cacheDir = cacheDir.getCanonicalFile();
    } catch (IOException e) {
      throw new VertxException("Cannot get canonical name of cacheDir", e);
    }
  }

  synchronized void registerShutdownHook() {
    Thread shutdownHook = new Thread(this::runHook);
    this.shutdownHook = shutdownHook;
    Runtime.getRuntime().addShutdownHook(shutdownHook);
  }

  private void runHook() {
    synchronized (this) {
      // no-op if cache dir has been set to null
      if (cacheDir == null) {
        return;
      }
    }
    Thread deleteCacheDirThread = new Thread(() -> {
      try {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the wrapped cause for the underlying I/O problem
2. Verify the cache directory path is valid and reachable
3. Set vertx.cacheDirBase to a simpler, existing path

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileCache.java:99 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/00fcb4b3bb42c3b7. Report an issue: GitHub.