eclipse-vertx/vert.x · error · RuntimeException

${packageFolderURL} is not a JAR file

Error message

${packageFolderURL} is not a JAR file

What it means

PackageHelper.browseJar scans a URL expected to point to a JAR archive to enumerate compiled verticle classes. When the URL cannot be opened as a JAR (the underlying JarInputStream/entries access fails), it wraps the failure in this RuntimeException identifying the offending URL.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/verticle/PackageHelper.java:88

  private static List<JavaFileObject> browseJar(URL packageFolderURL) {
    List<JavaFileObject> result = new ArrayList<>();
    try {
      String jarUri = packageFolderURL.toExternalForm().split("!")[0];
      JarURLConnection jarConn = (JarURLConnection) packageFolderURL.openConnection();
      String rootEntryName = jarConn.getEntryName();
      int rootEnd = rootEntryName.length() + 1;

      Enumeration<JarEntry> entryEnum = jarConn.getJarFile().entries();
      while (entryEnum.hasMoreElements()) {
        JarEntry jarEntry = entryEnum.nextElement();
        String name = jarEntry.getName();
        if (name.startsWith(rootEntryName) && name.indexOf('/', rootEnd) == -1 && name.endsWith(CLASS_FILE)) {
          String binaryName = name.replaceAll("/", ".").replaceAll(CLASS_FILE + "$", "");
          result.add(new CustomJavaFileObject(URI.create(jarUri + "!/" + name), JavaFileObject.Kind.CLASS, binaryName));
        }
      }
    } catch (Exception e) {
      throw new RuntimeException(packageFolderURL + " is not a JAR file", e);
    }
    return result;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Verify the URL/classpath entry actually points to a valid, non-corrupt JAR (test with `jar tf file.jar`)
2. Check the cause exception chained in the RuntimeException for the real I/O failure
3. If classes are in an exploded directory, ensure the resolution path used is the directory variant, not the JAR variant

try (JarFile jf = new JarFile(new File(url.toURI()))) { /* valid jar */ } catch (Exception e) { /* not a jar */ }

try {
  vertx.deployVerticle(packageName);
} catch (RuntimeException e) {
  if (e.getCause() != null) { log.warn("Classpath scan failed", e.getCause()); }
  // fall back to explicit verticle class names
}

When it happens

Trigger: Calling verticle resolution with a package folder URL that points to a plain directory, corrupt JAR, or non-archive resource during classpath scanning for verticles in a package.

Common situations: Classpath misconfiguration where a JAR was replaced by an exploded directory or truncated download; passing a directory URL to a helper that assumes a jar: URI.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Nesting more than two levels is not supported
• Failed to unpack ${url}
• Cannot find META-INF/services/${clazz} on classpath
• Cannot find service on the classpath or module path
• No ClusterManagerFactory instances found on classpath

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