eclipse-vertx/vert.x · error · IllegalArgumentException

Expecting a stripesCount that is larger than 0

Error message

Expecting a stripesCount that is larger than 0

What it means

HybridJacksonPool.StripedLockFreePool is the internal striped lock-free pool used by the Vert.x Jackson pool. Its constructor validates that stripesCount is > 0 and throws IllegalArgumentException('Expecting a stripesCount that is larger than 0') otherwise. This is an internal invariant check; users hit it only through misconfiguration of the pool, typically via system properties.

Source

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

    }
    // the native thread pool is based on ThreadLocal, so it doesn't have anything to do on release
  }

  public static class StripedLockFreePool implements RecyclerPool<BufferRecycler> {

    private static final int CACHE_LINE_SHIFT = 4;

    private static final int CACHE_LINE_PADDING = 1 << CACHE_LINE_SHIFT;

    private final XorShiftThreadProbe threadProbe;

    private final AtomicReferenceArray<Node> topStacks;

    private final int stripesCount;

    public StripedLockFreePool(int stripesCount) {
      if (stripesCount <= 0) {
        throw new IllegalArgumentException("Expecting a stripesCount that is larger than 0");
      }

      this.stripesCount = stripesCount;
      int size = roundToPowerOfTwo(stripesCount);
      this.topStacks = new AtomicReferenceArray<>(size * CACHE_LINE_PADDING);

      int mask = (size - 1) << CACHE_LINE_SHIFT;
      this.threadProbe = new XorShiftThreadProbe(mask);
    }

    public int size() {
      return stackSizes().sum();
    }

    public int[] stackStats() {
      return stackSizes().toArray();
    }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check JVM system properties configuring the Jackson pool; set the size to a positive value (e.g. 16 or 2*cores).
2. If sourcing from an env var, guard against unset/zero: use a default when the variable is absent or <= 0.
3. Do not instantiate StripedLockFreePool directly — it is internal; configure via supported Vert.x options/properties only.
4. Remove the invalid tuning property entirely to fall back to the default pool sizing.

Example fix

// before
-Dvertx.jsonPool.size=${POOL_SIZE}  # POOL_SIZE unset -> 0
// after
-Dvertx.jsonPool.size=${POOL_SIZE:-16}

int poolSize = Integer.getInteger("vertx.jacksonPool.size", Runtime.getRuntime().availableProcessors() * 2);
if (poolSize <= 0) {
  throw new IllegalStateException("vertx.jacksonPool.size must be > 0, got " + poolSize);
}

When it happens

Trigger: Constructing StripedLockFreePool with 0 or a negative value; setting the Vert.x Jackson pool configuration property (e.g. vertx.jacksonPool.size or the hybrid pool stripe count) to 0/negative or to a value that resolves to <= 0 at init.

Common situations: Tuning JSON parser pool size via -D properties in containers/K8s where the value came from an unset/zero env var ('0' string); copy-pasted tuning config from a blog; startup code configuring the pool before properties load.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• workerPoolSize must be > 0
• maxPoolSize must be > 0
• http2MaxPoolSize must be > 0
• http3MaxPoolSize must be > 0
• maxLifetime must be >= 0

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