eclipse-vertx/vert.x · error · IllegalStateException

Invalid url protocol:

Error message

Invalid url protocol: 

What it means

Protocol dispatch guard in FileResolverImpl.unpackUrlResource: the URL's protocol matched none of the supported schemes (file, jar, bundle*, jrt, resource, vfs). The unsupported protocol name is appended to the message; the resource cannot be unpacked to the cache from that URL type.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/FileResolverImpl.java:249

    return resource;
  }

  private File unpackUrlResource(URL url, String fileName, ClassLoader cl, boolean isDir) {
    String prot = url.getProtocol();
    switch (prot) {
      case "file":
        return unpackFromFileURL(url, fileName, cl);
      case "jar":
        return unpackFromJarURL(url, fileName, cl);
      case "bundle": // Apache Felix, Knopflerfish
      case "bundleentry": // Equinox
      case "bundleresource": // Equinox
      case "jrt": // java run-time (JEP 220)
      case "resource":  // substratevm (graal native image)
      case "vfs":  // jboss-vfs
        return unpackFromBundleURL(url, fileName, isDir);
      default:
        throw new IllegalStateException("Invalid url protocol: " + prot);
    }
  }


  private File unpackFromFileURL(URL url, String fileName, ClassLoader cl) {
    final File resource = new File(decodeURIComponent(url.getPath(), false));
    boolean isDirectory = resource.isDirectory();
    File cacheFile;
    try {
      cacheFile = cache.cacheFile(fileName, resource, !enableCaching);
    } catch (IOException e) {
      throw new VertxException(FileSystemImpl.getFileAccessErrorMessage("unpack", resource.getAbsolutePath()), e);
    }
    if (isDirectory) {
      String[] listing = resource.list();
      if (listing != null) {
        for (String file : listing) {
          String subResource = fileName + "/" + file;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use a resource URL with a supported protocol (file:, jar:, bundle:, jrt:, resource:, vfs:)
2. Serve the resource from the classpath in a standard container instead of an exotic protocol

When it happens

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