eclipse-vertx/vert.x · error · IllegalArgumentException

factory.prefix() cannot be null

Error message

factory.prefix() cannot be null

What it means

VerticleManager.registerVerticleFactory requires every VerticleFactory to expose a non-null prefix that namespaces deploy identifiers (e.g. 'service:'). A factory returning a null prefix cannot be keyed in the registry, so registration fails fast with IllegalArgumentException.

Source

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

  public VerticleManager(VertxInternal vertx, Logger log, DeploymentManager deploymentManager) {
    this.vertx = (VertxImpl) vertx;
    this.deploymentManager = deploymentManager;
    this.log = log;
  }

  public void init(List<VerticleFactory> factories) {
    if (factories != null) {
      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) {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Fix the custom factory's prefix() to return a non-null, non-empty string like "my-prefix"
2. Validate the prefix in the factory's constructor or init() so bad configuration surfaces early

Example fix

// before
public String prefix() { return config == null ? null : config.prefix; }
// after
public String prefix() { return "my-prefix"; }

if (factory.prefix() == null || factory.prefix().isEmpty()) {
  throw new IllegalStateException("Verticle factory prefix must be non-null");
}
vertx.registerVerticleFactory(factory);

try {
  vertx.registerVerticleFactory(factory);
} catch (IllegalArgumentException e) {
  log.error("Bad verticle factory: " + e.getMessage());
}

When it happens

Trigger: Implementing a custom VerticleFactory whose prefix() method returns null, then registering it via Vertx.registerVerticleFactory(factory).

Common situations: Custom factory implementations that compute the prefix dynamically and return null on a misconfigured instance; overriding prefix() in a subclass and forgetting the return value path.

Related errors

• cookie cannot be null
• Factory already registered
• factory isn't registered
• Invalid name: ${str}
• Cannot put null in key or value of async map

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