eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid name: ${str}

Error message

Invalid name: ${str}

What it means

When resolving deployment identifiers, getSuffix extracts the part after the last ':' delimiter (the factory prefix is the part before it). If the identifier ends with ':' or has no suffix, the name is malformed and cannot be dispatched to any verticle factory.

Source

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

      if (pos != -1) {
        lookup = getSuffix(pos, identifier);
      } else {
        // No prefix, no extension - use defaults
        factoryList = defaultFactories;
      }
    }
    if (factoryList == null) {
      factoryList = verticleFactories.get(lookup);
      if (factoryList == null) {
        factoryList = defaultFactories;
      }
    }
    return factoryList;
  }

  private static String getSuffix(int pos, String str) {
    if (pos + 1 >= str.length()) {
      throw new IllegalArgumentException("Invalid name: " + str);
    }
    return str.substring(pos + 1);
  }

  /**
   * Deploy a verticle given a deployment {@code identifier} and its specific {@code options}.
   *
   * @param identifier the verticle identifier
   * @param options the deployment options
   * @return a furur result of the deployment context
   */
  public Future<DeploymentContext> deployVerticle(String identifier, DeploymentOptions options) {
    ContextInternal callingContext = vertx.getOrCreateContext();
    ClassLoader loader = options.getClassLoader();
    if (loader == null) {
      loader = getCurrentClassLoader();
    }
    return deployVerticle(identifier, options, callingContext, callingContext, loader);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a complete identifier of the form "prefix:name", e.g. "service:com.acme.MyService"
2. Check the code/config that builds the deployment name for a trailing ':'
3. If deploying a plain class, omit the prefix entirely instead of leaving an empty suffix

Example fix

// before
vertx.deployVerticle("service:"); // throws
// after
vertx.deployVerticle("service:com.acme.MyService");

String identifier = "service:com.acme.MyService";
int i = identifier.lastIndexOf(':');
if (i != -1 && i + 1 >= identifier.length()) {
  throw new IllegalArgumentException("Deployment name needs a suffix after ':'");
}

try {
  vertx.deployVerticle(identifier);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Invalid name")) {
    log.error("Malformed deployment identifier: " + identifier);
  }
}

When it happens

Trigger: Deploying an identifier like "service:" or "myorg-" where a prefix is present but nothing follows it; calling deployVerticle("foo:").

Common situations: String-concatenation bugs building deployment names dynamically; configuration values where the suffix portion was accidentally stripped or the separator typed twice at the end.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• factory.prefix() cannot be null
• Factory already registered
• factory isn't registered

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