eclipse-vertx/vert.x · error · IllegalArgumentException

factory isn't registered

Error message

factory isn't registered

What it means

Thrown when unregisterVerticleFactory cannot find the given factory in its prefix's registered list. The manager only removes factories that were actually registered; unregistering an unknown factory is treated as a programming error.

Source

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

  }

  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;
      }
      if (facts.isEmpty()) {
        verticleFactories.remove(prefix);
      }
    }
    if (!removed) {
      throw new IllegalArgumentException("factory isn't registered");
    }
  }

  public Set<VerticleFactory> verticleFactories() {
    Set<VerticleFactory> facts = new HashSet<>();
    for (List<VerticleFactory> list: verticleFactories.values()) {
      facts.addAll(list);
    }
    return facts;
  }

  private List<VerticleFactory> resolveFactories(String identifier) {
    /*
      We resolve the verticle factory list to use as follows:
      1. We look for a prefix in the identifier.
      E.g. the identifier might be "js:app.js" <-- the prefix is "js"
      If it exists we use that to lookup the verticle factory list
      2. We look for a suffix (like a file extension),

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Only unregister factories you registered on the same Vertx instance
2. Track registration state (e.g. an AtomicBoolean) and skip redundant unregister calls
3. Ignore/absorb the IllegalArgumentException if best-effort cleanup is intended

Example fix

// before
vertx.unregisterVerticleFactory(factory); // throws if not registered
// after
if (registered.compareAndSet(true, false)) {
  vertx.unregisterVerticleFactory(factory);
}

if (registeredFactories.remove(factory)) {
  vertx.unregisterVerticleFactory(factory);
}

try {
  vertx.unregisterVerticleFactory(factory);
} catch (IllegalArgumentException e) {
  if ("factory isn't registered".equals(e.getMessage())) return; // best-effort cleanup
  throw e;
}

When it happens

Trigger: Calling unregisterVerticleFactory with a factory never registered on this Vertx, or already unregistered, or a different instance with the same prefix.

Common situations: Double-cleanup in shutdown code; factory registered on a different Vertx instance than the one being cleaned up; tests unregistering a shared mock multiple times.

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

• factory.prefix() cannot be null
• Factory already registered
• Invalid name: ${str}

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