eclipse-vertx/vert.x · error · VertxException

unpack

Error message

unpack

What it means

Wrap of an IOException raised while unpacking a file:// resource into the file cache (unpackFromFileURL). The message 'unpack' is the failing operation label; the concrete cause (copy failure, cache write error) is carried in the exception's cause chain.

Source

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

      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;
          URL url2 = getValidClassLoaderResource(cl, subResource);
          unpackFromFileURL(url2, subResource, cl);
        }
      }
    }
    return cacheFile;
  }

  /**
   * Parse the list of entries of a URL assuming the URL is a jar URL.
   *
   * <ul>

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the cause for the real I/O failure
2. Verify the source file and the cache directory are readable/writable
3. Retry after resolving disk or permission issues

When it happens

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