eclipse-vertx/vert.x · warning · IllegalArgumentException

workerPoolSize must be > 0

Error message

workerPoolSize must be > 0

What it means

This is a log warning (not an exception) emitted by JacksonCodec.buildFactory in the Vert.x JSON Jackson (Jackson 3 / Java 21 variant) module. When reading a Jackson read-constraint system property (e.g. vertx.jackson_default_read_max_nesting_depth) via SysProps.getAsInt(), a non-numeric value causes IllegalArgumentException; the codec logs the invalid value and falls back to StreamReadConstraints.DEFAULT_MAX_DEPTH.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/VertxOptions.java:236

   * Get the maximum number of worker threads to be used by the Vert.x instance.
   * <p>
   * Worker threads are used for running blocking code and worker verticles.
   *
   * @return the maximum number of worker threads
   */
  public int getWorkerPoolSize() {
    return workerPoolSize;
  }

  /**
   * Set the maximum number of worker threads to be used by the Vert.x instance.
   *
   * @param workerPoolSize the number of threads
   * @return a reference to this, so the API can be used fluently
   */
  public VertxOptions setWorkerPoolSize(int workerPoolSize) {
    if (workerPoolSize < 1) {
      throw new IllegalArgumentException("workerPoolSize must be > 0");
    }
    this.workerPoolSize = workerPoolSize;
    return this;
  }

  /**
   * Get the value of blocked thread check period, in {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit}.
   * <p>
   * This setting determines how often Vert.x will check whether event loop threads are executing for too long.
   * <p>
   * The default value of {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit} is {@link TimeUnit#MILLISECONDS}.
   *
   * @return the value of blocked thread check period, in {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit}.
   */
  public long getBlockedThreadCheckInterval() {
    return blockedThreadCheckInterval;
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Remove or correct the system property so it parses as a plain integer (e.g. -Dvertx.jackson_default_read_max_nesting_depth=1000).
2. If the default constraint (StreamReadConstraints.DEFAULT_MAX_DEPTH) is acceptable, simply unset the property.
3. Check JVM launch scripts, container env -> -D translation, and start/stop scripts for stale or malformed property values.
4. Restart the JVM after fixing: system properties are read once when the codec factory is built.

Example fix

// before (JVM args)
-Dvertx.jackson_default_read_max_nesting_depth=10x
// after
-Dvertx.jackson_default_read_max_nesting_depth=1000

String v = System.getProperty("vertx.jackson_default_read_max_nesting_depth", "");
if (!v.isEmpty()) {
  try { Integer.parseInt(v.trim()); } catch (NumberFormatException e) {
    throw new IllegalStateException("vertx.jackson_default_read_max_nesting_depth must be an integer, got: " + v);
  }
}

When it happens

Trigger: Setting a Jackson constraint system property (JACKSON_DEFAULT_READ_MAX_NESTING_DEPTH, and similarly the max doc length property) to a value that cannot be parsed as an integer/long (e.g. empty string or 'abc') before building the JSON codec factory.

Common situations: Typos or units accidentally added to JVM options (-Dvertx.jackson_default_read_max_nesting_depth=10x), config templating that interpolates an empty or placeholder value, YAML/properties files quoting values as strings.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Failed to encode as JSON: ${e.getMessage()}
• Expected an ISO 8601 formatted date time
• Failed to decode:${e.getMessage()}
• Failed to decode:
• Expecting the current parser token to be the start of an obj

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