eclipse-vertx/vert.x · error · IllegalStateException

Cannot find vertx-version.txt on classpath

Error message

Cannot find vertx-version.txt on classpath

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java:1343

      if (local != null) {
        local = ((Function)contextLocal.duplicator).apply(local);
      }
      AccessMode.CONCURRENT.put(dst.locals, i, local);
    }
  }

  /**
   * Reads the version from the {@code vertx-version.txt} file.
   *
   * @return the version
   */
  public static String version() {
    if (version != null) {
      return version;
    }
    try (InputStream is = VertxImpl.class.getClassLoader().getResourceAsStream("META-INF/vertx/vertx-version.txt")) {
      if (is == null) {
        throw new IllegalStateException("Cannot find vertx-version.txt on classpath");
      }
      try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8).useDelimiter("\\A")) {
        return version = scanner.hasNext() ? scanner.next().trim() : "";
      }
    } catch (IOException e) {
      throw new IllegalStateException(e.getMessage());
    }
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Fix the build/shade config so META-INF/vertx/vertx-version.txt from vertx-core is included in the artifact
2. If using shade/assembly transformers, add a resource transformer that keeps (or merges) vertx-version.txt
3. Verify with jar tf or by loading the resource in a smoke test before release
4. Don't exclude META-INF/** in resource filtering sections

Example fix

// before (maven-shade)
<filter><artifact>*:*</artifact><excludes><exclude>META-INF/**</exclude></excludes></filter>
// after
<filter><artifact>*:*</artifact><excludes><exclude>META-INF/*.SF</exclude><exclude>META-INF/*.DSA</exclude></excludes></filter>

try (InputStream is = getClass().getClassLoader()
    .getResourceAsStream("META-INF/vertx/vertx-version.txt")) {
  if (is == null) throw new IllegalStateException("vertx-version.txt missing from classpath");
}

try {
  String v = Vertx.version();
} catch (IllegalStateException e) {
  // report broken packaging; degrade version reporting to "unknown"
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Nesting more than two levels is not supported
• Unsupported HTTP version: <version>
• 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/2bbfd5b15f891108. Report an issue: GitHub.