{"record":{"id":"f0443552f94a8d14","repo":"eclipse-vertx/vert.x","slug":"failed-to-unpack-url","errorCode":null,"errorMessage":"Failed to unpack ${url}","messagePattern":"Failed to unpack (.+?)","errorType":"exception","errorClass":"VertxException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/file/impl/FileResolverImpl.java","lineNumber":367,"sourceCode":"                  cache.cacheFile(relative.toString(), file.toFile(), false);\n                  return FileVisitResult.CONTINUE;\n                }\n              });\n            } else {\n              // jar:file:/path/to/nesting.jar!/path/to/nested.jar\n              try (ZipFile zip = new ZipFile(root)) {\n                extractFilesFromJarFile(zip, fileName);\n              }\n            }\n          } else {\n            throw new VertxException(\"Unexpected nested url : \" + nestedURL);\n          }\n          break;\n        default:\n          throw new VertxException(\"Nesting more than two levels is not supported\");\n      }\n    } catch (IOException e) {\n      throw new VertxException(FileSystemImpl.getFileAccessErrorMessage(\"unpack\", url.toString()), e);\n    }\n    return cache.getFile(fileName);\n  }\n\n  /**\n   * Extract a subset of the entries to the cache.\n   */\n  private void extractFilesFromJarFile(ZipFile zip, String entryFilter) throws IOException {\n    Enumeration<? extends ZipEntry> entries = zip.entries();\n    while (entries.hasMoreElements()) {\n      ZipEntry entry = entries.nextElement();\n      String name = entry.getName();\n      int len = name.length();\n      if (len == 0) {\n        return;\n      }\n      if (name.charAt(len - 1) != ' ' || !Utils.isWindows()) {\n        if (name.startsWith(entryFilter)) {","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/file/impl/FileResolverImpl.java#L349-L385","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the 'cause' IOException/ZipException: if it is a zip/format error, rebuild the jar (mvn clean package) and redeploy.","Ensure the temp/cache location is writable and has free space (check java.io.tmpdir / VERTX_CACHE dir; set -Dvertx.cacheDirBase=/writable/path).","Verify the jar file exists and is not being overwritten during runtime (stop the app before redeploying the jar).","Set -Dvertx.disableFileCPResolving=true if you read resources via classloader streams instead of file APIs, avoiding unpacking entirely."],"exampleFix":"// before\nvertx.fileSystem().readFileBlocking(\"conf.json\"); // unpacks jar, may fail\n// after: read via classloader so no unpack is needed\ntry (InputStream in = getClass().getClassLoader().getResourceAsStream(\"conf.json\")) {\n  Buffer buf = Buffer.buffer(in.readAllBytes());\n}","handlingStrategy":"try-catch","validationCode":"URL url = cl.getResource(name);\nif (url == null) throw new FileNotFoundException(name);\nif (url.getProtocol().equals(\"jar\")) {\n  try (JarFile jar = ((JarURLConnection) url.openConnection()).getJarFile()) {\n    jar.getJarEntry(name); // throws IOException early if jar is corrupt\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return vertx.fileSystem().readFileBlocking(resource);\n} catch (VertxException e) {\n  if (e.getCause() instanceof java.util.zip.ZipException) {\n    throw new IllegalStateException(\"Corrupt jar containing \" + resource + \", rebuild it\", e);\n  }\n  throw e;\n}","preventionTips":["Verify jar integrity after build (mvn verify / checksum check) before deployment","Never overwrite a jar while the application is running","Point -Dvertx.cacheDirBase at a writable, non-full volume","Prefer ClassLoader.getResourceAsStream for jar-internal resources"],"tags":["file-system","io","jar","unpack"],"backgroundTag":"file-read-failed","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}