eclipse-vertx/vert.x · error · IllegalArgumentException

Given value:

Error message

Given value:

What it means

HybridJacksonPool.roundToPowerOfTwo validates pool sizing arguments before rounding them to the next power of two. It throws IllegalArgumentException when the value exceeds the maximum representable power of two (2^31 as an int, capped by MAX_POW2) or when the value is negative. It is an internal guard that signals invalid capacity arguments, not a JSON data problem.

Source

Thrown at vertx-core/src/main/java21/io/vertx/core/json/jackson/v3/HybridJacksonPool.java:205

      // multiplied by 2^32, which has the best possible scattering properties.
      int probe = (int) ((Thread.currentThread().getId() * 0x9e3779b9) & Integer.MAX_VALUE);
      // xorshift
      probe ^= probe << 13;
      probe ^= probe >>> 17;
      probe ^= probe << 5;
      return probe;
    }
  }

  private static final int MAX_POW2 = 1 << 30;

  private static int roundToPowerOfTwo(final int value) {
    if (value > MAX_POW2) {
      throw new IllegalArgumentException(
        "There is no larger power of 2 int for value:" + value + " since it exceeds 2^31.");
    }
    if (value < 0) {
      throw new IllegalArgumentException("Given value:" + value + ". Expecting value >= 0.");
    }
    final int nextPow2 = 1 << (32 - Integer.numberOfLeadingZeros(value - 1));
    return nextPow2;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Verify the value passed to the pool-sizing API is non-negative and <= MAX_POW2 (2^31 as an int is the practical cap)
2. Clamp or validate the configured size before passing it: Math.max(0, Math.min(value, MAX_POW2))
3. Fix the configuration/derivation that produced a negative or oversized value (e.g. check for int overflow in size computation)

Example fix

// before
int size = Integer.getInteger("pool.size", -1);
JsonPool pool = HybridJacksonPool.getInstance(size); // IllegalArgumentException
// after
int size = Integer.getInteger("pool.size", 16);
if (size < 0 || size > HybridJacksonPool.MAX_POW2) size = 16;
JsonPool pool = HybridJacksonPool.getInstance(size);

if (value < 0 || value > MAX_POW2) {
  throw new IllegalArgumentException("pool size out of range: " + value);
}
JsonPool pool = HybridJacksonPool.getInstance(value);

static boolean isValidPoolSize(int v) { return v >= 0 && v <= (1 << 30); }

When it happens

Trigger: Calling pool/queue sizing APIs (e.g. HybridJacksonPool factory methods or underlying VertxPool arguments) with a capacity greater than MAX_POW2 (over 2^31 as an int) or with a negative number such as a negative initial size passed to a pooled parser factory.

Common situations: Configuration files where a pool-size or buffer-capacity property is computed (e.g. a size derived from another value becoming negative due to an int overflow), or copy-pasted configuration using bytes as the unit when the API expects a small count.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• workerPoolSize must be > 0
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0

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