eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid ${argName}: ${arg}

Error message

Invalid ${argName}: ${arg}

What it means

Args.getInt parses a named string argument from a map into an int. When the value exists but cannot be parsed by Integer.parseInt, an IllegalArgumentException('Invalid <name>: <value>') is thrown. Missing values silently return -1 instead of throwing.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/Args.java:51

        if (currentKey != null) {
          map.put(currentKey, arg);
          currentKey = null;
        }
      }
    }
    if (currentKey != null) {
      map.put(currentKey, "");
    }
  }

  public int getInt(String argName) {
    String arg = map.get(argName);
    int val;
    if (arg != null) {
      try {
        val = Integer.parseInt(arg.trim());
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Invalid " + argName + ": " + arg);
      }
    } else {
      val = -1;
    }
    return val;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check the value printed in the message and fix the argument so it is a valid integer (trimmed decimal digits)
2. Verify how the argument map is populated (launch script, system property, JSON) and correct the source value
3. If a missing value is expected, note getInt returns -1 and validate the -1 case at the call site instead of relying on parsing

Example fix

// before
vertx.runVerticle(MainVerticle.class, new DeploymentOptions().setInstances(Integer.parseInt(args.value("-instances"))));
// after
String raw = args.value("-instances");
if (raw == null || !raw.trim().matches("\\d+")) {
  throw new IllegalArgumentException("-instances must be an integer, got: " + raw);
}

if (raw != null && !raw.trim().matches("-?\\d+")) throw new IllegalArgumentException("-instances must be an integer, got: " + raw);

boolean isInt(String s){ return s != null && s.trim().matches("-?\\d+"); }

When it happens

Trigger: Calling getInt(argName) on an Args/option map whose stored value is a non-numeric string (e.g. 'abc', '', '12x') for options like -cluster-port or -instances.

Common situations: Launcher CLI options passed via -D or command line with typos; quoting issues in scripts leaving empty or whitespace-polluted values; user-supplied config files where a port was meant but text was entered.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Can't register a system codec
• Cannot open file for neither reading nor writing
• Invalid setting
• maxWebSockets must be > 0 or -1 (disabled)
• code: <statusCode> (expected: 0+)

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