eclipse-vertx/vert.x · error · RuntimeException

Package structure does not match directory structure: ${toke

Error message

Package structure does not match directory structure: ${token} != ${rootDirectory.getName()}

What it means

Thrown when compiling a Java verticle from source: the verticle's declared package name must match the directory hierarchy under the source root. The compiler walks the package tokens backwards against parent directories, and any mismatch aborts compilation because the resulting class file could not be placed correctly.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/verticle/JavaSourceContext.java:38

 *
 * Resolves package name and source path based on a single Java source file.
 *
 * @author Janne Hietamäki
 */
public class JavaSourceContext {

  private final String className;
  private final File sourceRoot;

  public JavaSourceContext(File file) {
    String packageName = parsePackage(file);
    File rootDirectory = file.getParentFile();
    if (packageName != null) {
      String[] pathTokens = packageName.split("\\.");
      for(int i = pathTokens.length - 1; i >= 0; i--) {
        String token = pathTokens[i];
        if (!token.equals(rootDirectory.getName())) {
          throw new RuntimeException("Package structure does not match directory structure: " + token + " != " + rootDirectory.getName());
        }
        rootDirectory = rootDirectory.getParentFile();
      }
    }
    sourceRoot = rootDirectory;

    String fileName = file.getName();
    String className = fileName.substring(0, fileName.length() - Kind.SOURCE.extension.length());
    if (packageName != null) {
      className = packageName + '.' + className;
    }
    this.className = className;
  }

  public File getSourceRoot() {
    return sourceRoot;
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Move the .java file so its directory path matches the package declaration
2. Remove or correct the `package` statement in the source file to reflect the real directory structure
3. Deploy the verticle from the correct source root directory

Example fix

// before: file at ./MyVerticle.java declaring
package com.example.verticles;
public class MyVerticle extends AbstractVerticle { ... }
// after: move file to ./com/example/verticles/MyVerticle.java or delete the package line

Path src = Paths.get("MyVerticle.java");
String pkg = extractPackageDeclaration(src);
Path dir = src.getParent();
String[] tokens = pkg.split("\\.");
Path cur = dir;
for (int i = tokens.length - 1; i >= 0; i--) {
  if (cur == null || !tokens[i].equals(cur.getFileName().toString())) {
    throw new IllegalStateException("Package/dir mismatch at " + tokens[i]);
  }
  cur = cur.getParent();
}

When it happens

Trigger: Calling Vertx.deployVerticle with a .java file whose `package x.y.z;` declaration does not correspond to its actual directory layout, e.g. the file sits in a directory whose name differs from the last package token.

Common situations: Renaming or moving a verticle source file without updating the package declaration; copying a .java file into a flat directory while it still declares a package; IDE-generated sources relocated manually.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Supplied deployable is null
• Same deployable supplied more than once
• Invalid identifier: ${identifer}

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