eclipse-vertx/vert.x · error · VertxException

File is outside of the cacheDir dir:

Error message

File is outside of the cacheDir dir: 

What it means

Security guard in FileCache.fileNameCheck: the canonical path of the target cache file does not start with the cache directory path, i.e. the file name escapes the cache dir (path traversal). Caching or reading such a file is refused to prevent writes outside the cache; the offending file is appended to the message.

Source

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

    if (!overwrite) {
      try {
        Files.copy(is, cacheFile.toPath());
      } catch (FileAlreadyExistsException ignore) {
      }
    } else {
      Files.copy(is, cacheFile.toPath(), StandardCopyOption.REPLACE_EXISTING);
    }
  }

  void cacheDir(String fileName) throws IOException {
    File file = new File(getCacheDir(), fileName);
    fileNameCheck(file);
    file.mkdirs();
  }

  private void fileNameCheck(File file) throws IOException {
    if (!file.getCanonicalFile().toPath().startsWith(getCacheDir().toPath())) {
      throw new VertxException("File is outside of the cacheDir dir: " + file);
    }
  }

  private File getCacheDir() {
    File currentCacheDir = cacheDir;
    if (currentCacheDir == null) {
      throw new IllegalStateException("cacheDir has been removed. FileResolver is closing?");
    }
    return currentCacheDir;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Reject or sanitize file names containing '..' or absolute-path components before calling cacheFile/cacheDir
2. Validate resource names from untrusted sources

When it happens

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