eclipse-vertx/vert.x · error · VertxException

Failed to unpack ${url}

Error message

Failed to unpack ${url}

What it means

unpackFromJarURL wraps any IOException raised while opening streams from the jar URL or writing extracted entries into the cache directory, rethrowing as VertxException with 'Failed to unpack <url>'. The library throws this because classpath resources inside jars must be materialized to a temp/cache dir for file-based APIs to work, and the extraction I/O failed. The original IOException is attached as cause.

Source

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

                  cache.cacheFile(relative.toString(), file.toFile(), false);
                  return FileVisitResult.CONTINUE;
                }
              });
            } else {
              // jar:file:/path/to/nesting.jar!/path/to/nested.jar
              try (ZipFile zip = new ZipFile(root)) {
                extractFilesFromJarFile(zip, fileName);
              }
            }
          } else {
            throw new VertxException("Unexpected nested url : " + nestedURL);
          }
          break;
        default:
          throw new VertxException("Nesting more than two levels is not supported");
      }
    } catch (IOException e) {
      throw new VertxException(FileSystemImpl.getFileAccessErrorMessage("unpack", url.toString()), e);
    }
    return cache.getFile(fileName);
  }

  /**
   * Extract a subset of the entries to the cache.
   */
  private void extractFilesFromJarFile(ZipFile zip, String entryFilter) throws IOException {
    Enumeration<? extends ZipEntry> entries = zip.entries();
    while (entries.hasMoreElements()) {
      ZipEntry entry = entries.nextElement();
      String name = entry.getName();
      int len = name.length();
      if (len == 0) {
        return;
      }
      if (name.charAt(len - 1) != ' ' || !Utils.isWindows()) {
        if (name.startsWith(entryFilter)) {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Inspect the 'cause' IOException/ZipException: if it is a zip/format error, rebuild the jar (mvn clean package) and redeploy.
2. Ensure the temp/cache location is writable and has free space (check java.io.tmpdir / VERTX_CACHE dir; set -Dvertx.cacheDirBase=/writable/path).
3. Verify the jar file exists and is not being overwritten during runtime (stop the app before redeploying the jar).
4. Set -Dvertx.disableFileCPResolving=true if you read resources via classloader streams instead of file APIs, avoiding unpacking entirely.

Example fix

// before
vertx.fileSystem().readFileBlocking("conf.json"); // unpacks jar, may fail
// after: read via classloader so no unpack is needed
try (InputStream in = getClass().getClassLoader().getResourceAsStream("conf.json")) {
  Buffer buf = Buffer.buffer(in.readAllBytes());
}

URL url = cl.getResource(name);
if (url == null) throw new FileNotFoundException(name);
if (url.getProtocol().equals("jar")) {
  try (JarFile jar = ((JarURLConnection) url.openConnection()).getJarFile()) {
    jar.getJarEntry(name); // throws IOException early if jar is corrupt
  }
}

try {
  return vertx.fileSystem().readFileBlocking(resource);
} catch (VertxException e) {
  if (e.getCause() instanceof java.util.zip.ZipException) {
    throw new IllegalStateException("Corrupt jar containing " + resource + ", rebuild it", e);
  }
  throw e;
}

When it happens

Trigger: vertx.fileSystem() operations or verticle deployment triggering FileResolver.unpackUrlResource -> unpackFromJarURL when the jar URL stream cannot be opened (corrupt/truncated jar, jar deleted while running, ZipException on a malformed entry) or the cache/temp directory write fails.

Common situations: Corrupted jar produced by an interrupted build; jar file modified or replaced on a live deployment; disk full or read-only /tmp where the Vert.x cache dir lives; permissions on the temp directory; antivirus locking the jar on Windows.

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

• Failed to copy ${from} to ${to}
• Failed to move ${from} to ${to}
• Failed to truncate ${p}
• Nesting more than two levels is not supported
• Cannot truncate file to size < 0

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