eclipse-vertx/vert.x · error · IllegalArgumentException

quorumSize should be >= 1

Error message

quorumSize should be >= 1

What it means

VertxOptions.setQuorumSize throws IllegalArgumentException with "quorumSize should be >= 1" when a value below 1 is supplied. The quorum size is used in clustered Vert.x deployments: it is the minimum number of nodes that must be active in the cluster before HA deployment of modules proceeds. Zero or negative quorums are nonsensical (a quorum of 0 would deploy HA modules on an empty cluster).

Source

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

  /**
   * Get the quorum size to be used when HA is enabled.
   *
   * @return the quorum size
   */
  public int getQuorumSize() {
    return quorumSize;
  }

  /**
   * Set the quorum size to be used when HA is enabled.
   *
   * @param quorumSize the quorum size
   * @return a reference to this, so the API can be used fluently
   */
  public VertxOptions setQuorumSize(int quorumSize) {
    if (quorumSize < 1) {
      throw new IllegalArgumentException("quorumSize should be >= 1");
    }
    this.quorumSize = quorumSize;
    return this;
  }

  /**
   * Get the HA group to be used when HA is enabled.
   *
   * @return the HA group
   */
  public String getHAGroup() {
    return haGroup;
  }

  /**
   * Set the HA group to be used when HA is enabled.
   *
   * @param haGroup the HA group to use

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a quorum >= 1, typically (clusterSize / 2) + 1 for majority semantics.
2. To disable HA/quorum behavior, use the cluster HA options (e.g. setHa(false) or setQuorumSize only when HA is on) rather than passing 0.
3. Validate config JSON before fromJson so quorumSize is either absent (default 1) or >= 1.

Example fix

// before
opts.setQuorumSize(nodes.size() / 2); // 0 for empty/1-node list
// after
opts.setQuorumSize(Math.max(1, nodes.size() / 2 + 1));

int quorum = ha ? Math.max(1, nodes.size() / 2 + 1) : 1;
if (quorum < 1) throw new IllegalArgumentException("quorumSize must be >= 1");
options.setQuorumSize(quorum);

try {
  options.setQuorumSize(q);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("quorumSize in cluster config must be >= 1, got " + q, e);
}

When it happens

Trigger: new VertxOptions().setQuorumSize(0) or negative; VertxOptions.fromJson with "quorumSize" <= 0; cluster startup code (e.g. startVertx) deriving quorum from the number of configured nodes when that list is empty.

Common situations: Computing quorumSize as nodes.size()/2+1 with an empty node list; config files where quorum is intentionally 0 to 'disable' HA instead of leaving the default; migrating configs where quorumSize was omitted and defaulted incorrectly.

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

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

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