{"record":{"id":"2bbfd5b15f891108","repo":"eclipse-vertx/vert.x","slug":"cannot-find-vertx-version-txt-on-classpath","errorCode":null,"errorMessage":"Cannot find vertx-version.txt on classpath","messagePattern":"Cannot find vertx-version\\.txt on classpath","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java","lineNumber":1343,"sourceCode":"      if (local != null) {\n        local = ((Function)contextLocal.duplicator).apply(local);\n      }\n      AccessMode.CONCURRENT.put(dst.locals, i, local);\n    }\n  }\n\n  /**\n   * Reads the version from the {@code vertx-version.txt} file.\n   *\n   * @return the version\n   */\n  public static String version() {\n    if (version != null) {\n      return version;\n    }\n    try (InputStream is = VertxImpl.class.getClassLoader().getResourceAsStream(\"META-INF/vertx/vertx-version.txt\")) {\n      if (is == null) {\n        throw new IllegalStateException(\"Cannot find vertx-version.txt on classpath\");\n      }\n      try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8).useDelimiter(\"\\\\A\")) {\n        return version = scanner.hasNext() ? scanner.next().trim() : \"\";\n      }\n    } catch (IOException e) {\n      throw new IllegalStateException(e.getMessage());\n    }\n  }\n}\n","sourceCodeStart":1325,"sourceCodeEnd":1353,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java#L1325-L1353","documentation":"Vertx.version() reads META-INF/vertx/vertx-version.txt from the classpath; if the resource is absent it throws IllegalStateException. The file is packaged in the vertx-core jar, so its absence signals a broken/partial classpath or shading that dropped the resource.","triggerScenarios":"Calling Vertx.version() (directly or via code paths that log/report the version) when META-INF/vertx/vertx-version.txt is not on the classpath — fat jars built without the resource, shaded jars with resource filtering, classpath assembled manually.","commonSituations":"Maven Shade/Gradle shadow configs excluding META-INF; Spring Boot repackaging dropping the resource; custom module path/dependency exclusions removing vertx-core resources; running with a hand-built classpath missing the jar's resources.","solutions":["Fix the build/shade config so META-INF/vertx/vertx-version.txt from vertx-core is included in the artifact","If using shade/assembly transformers, add a resource transformer that keeps (or merges) vertx-version.txt","Verify with jar tf or by loading the resource in a smoke test before release","Don't exclude META-INF/** in resource filtering sections"],"exampleFix":"// before (maven-shade)\n<filter><artifact>*:*</artifact><excludes><exclude>META-INF/**</exclude></excludes></filter>\n// after\n<filter><artifact>*:*</artifact><excludes><exclude>META-INF/*.SF</exclude><exclude>META-INF/*.DSA</exclude></excludes></filter>","handlingStrategy":"try-catch","validationCode":"try (InputStream is = getClass().getClassLoader()\n    .getResourceAsStream(\"META-INF/vertx/vertx-version.txt\")) {\n  if (is == null) throw new IllegalStateException(\"vertx-version.txt missing from classpath\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  String v = Vertx.version();\n} catch (IllegalStateException e) {\n  // report broken packaging; degrade version reporting to \"unknown\"\n}","preventionTips":["Add a build smoke test asserting META-INF/vertx/vertx-version.txt exists in the artifact","Review shade/assembly excludes so vertx-core resources survive packaging","Avoid blanket META-INF/** exclusions in resource filters"],"tags":["classpath","packaging","versioning","shading"],"backgroundTag":"resource-not-found","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}