eclipse-vertx/vert.x · error · IllegalArgumentException

Factory already registered

Error message

Factory already registered

What it means

Registering the exact same VerticleFactory instance twice is rejected. The manager keeps a list per prefix and checks contains(factory) before adding, throwing IllegalArgumentException to prevent duplicate registration and double init().

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/verticle/VerticleManager.java:71

      factories.forEach(this::registerVerticleFactory);
    }
    VerticleFactory defaultFactory = new JavaVerticleFactory();
    defaultFactory.init(vertx);
    defaultFactories.add(defaultFactory);
  }

  public void registerVerticleFactory(VerticleFactory factory) {
    String prefix = factory.prefix();
    if (prefix == null) {
      throw new IllegalArgumentException("factory.prefix() cannot be null");
    }
    List<VerticleFactory> facts = verticleFactories.get(prefix);
    if (facts == null) {
      facts = new ArrayList<>();
      verticleFactories.put(prefix, facts);
    }
    if (facts.contains(factory)) {
      throw new IllegalArgumentException("Factory already registered");
    }
    facts.add(factory);
    // Sort list in ascending order
    facts.sort((fact1, fact2) -> fact1.order() - fact2.order());
    factory.init(vertx);
  }

  public void unregisterVerticleFactory(VerticleFactory factory) {
    String prefix = factory.prefix();
    if (prefix == null) {
      throw new IllegalArgumentException("factory.prefix() cannot be null");
    }
    List<VerticleFactory> facts = verticleFactories.get(prefix);
    boolean removed = false;
    if (facts != null) {
      if (facts.remove(factory)) {
        removed = true;
      }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Guard registration: call registerVerticleFactory only once per Vertx instance per factory instance
2. Create a new factory instance for each Vertx, or check verticleFactories() for prior registration
3. Unregister the factory first with unregisterVerticleFactory before re-registering

Example fix

// before
vertx.registerVerticleFactory(factory);
vertx.registerVerticleFactory(factory); // throws
// after
if (!vertx.verticleFactories().contains(factory)) {
  vertx.registerVerticleFactory(factory);
}

boolean alreadyRegistered = vertx.verticleFactories().contains(factory);
if (!alreadyRegistered) {
  vertx.registerVerticleFactory(factory);
}

try {
  vertx.registerVerticleFactory(factory);
} catch (IllegalArgumentException e) {
  if (!"Factory already registered".equals(e.getMessage())) throw e;
  // idempotent: already registered, ignore
}

When it happens

Trigger: Calling registerVerticleFactory twice with the same factory instance (same object identity), typically during repeated bootstrap code, hot redeploy, or re-run initialization.

Common situations: Vertx instance recreated but factory held in a static/singleton field and registered again; framework bootstrap code executed multiple times.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Already a codec registered with name
• Already a default codec registered for class
• factory.prefix() cannot be null
• factory isn't registered
• Invalid name: ${str}

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