eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid identifier: ${identifer}

Error message

Invalid identifier: ${identifer}

What it means

VerticleFactory.removePrefix strips the '<prefix>:' portion of a verticle deployment identifier. If the identifier ends with a colon there is nothing after the prefix, so it throws IllegalArgumentException reporting the full identifier.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/spi/VerticleFactory.java:38

 * Has responsibility for creating verticle instances.
 * <p>
 * Implementations of this are responsible for creating verticle written in various different JVM languages and
 * for other purposes.
 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
public interface VerticleFactory {

  /**
   * Helper method to remove a prefix from an identifier string
   * @param identifer the identifier
   * @return  The identifier without the prefix (if it had any)
   */
  static String removePrefix(String identifer) {
    int pos = identifer.indexOf(':');
    if (pos != -1) {
      if (pos == identifer.length() - 1) {
        throw new IllegalArgumentException("Invalid identifier: " + identifer);
      }
      return identifer.substring(pos + 1);
    } else {
      return identifer;
    }
  }

  /**
   * The order of the factory. If there is more than one matching verticle they will be tried in ascending order.
   * @return  the order
   */
  default int order() {
    return 0;
  }

  /**
   * Initialise the factory
   * @param vertx  The Vert.x instance

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Supply a full identifier including the part after the colon, e.g. 'js:my_verticle.js'.
2. Validate the deployment string in your config before calling deployVerticle (must contain non-empty text after ':').
3. If no prefix is needed, pass the bare identifier (no colon) — removePrefix then returns it unchanged.

Example fix

// before
String ident = "js:"; // from truncated config
vertx.deployVerticle(ident); // IllegalArgumentException
// after
String ident = config.contains("verticle") ? config.getString("verticle") : "js:app.js";
if (ident.endsWith(":")) throw new IllegalArgumentException("missing verticle name after prefix");
vertx.deployVerticle(ident);

static void validateVerticleIdentifier(String ident) {
  int pos = ident.indexOf(':');
  if (pos == ident.length() - 1) throw new IllegalArgumentException("empty verticle name after prefix: " + ident);
}

try {
  vertx.deployVerticle(identifier);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid identifier")) {
    identifier = defaultPrefix + ":" + defaultVerticle;
  } else throw e;
}

When it happens

Trigger: Deploying a verticle with an identifier like 'js:' or 'java:' — the prefix separator exists but the actual identifier part is empty.

Common situations: Config-driven deployment where the identifier came from a truncated property/env var; string concatenation built the prefix but forgot the verticle name (e.g. prefix + ":" without appending the class file).

Related errors

• Supplied deployable is null
• Same deployable supplied more than once
• Can't register a system codec
• Cannot open file for neither reading nor writing
• Invalid setting

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