openzipkin/zipkin · error · IllegalArgumentException

maxConnections <= 0

Error message

maxConnections <= 0

What it means

CassandraStorageBuilder.maxConnections(int) throws IllegalArgumentException ('maxConnections <= 0') when a non-positive pool size is configured. This is the max pooled connections per datacenter-local host (default 8); zero or negative pools cannot serve any request, so the builder rejects the value immediately.

Source

Thrown at zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/CassandraStorageBuilder.java:117

  public B contactPoints(String contactPoints) {
    if (contactPoints == null) throw new NullPointerException("contactPoints == null");
    this.contactPoints = contactPoints;
    return (B) this;
  }

  /**
   * Name of the datacenter that will be considered "local" for latency load balancing. When unset,
   * load-balancing is round-robin.
   */
  public B localDc(String localDc) {
    if (localDc == null) throw new NullPointerException("localDc == null");
    this.localDc = localDc;
    return (B) this;
  }

  /** Max pooled connections per datacenter-local host. Defaults to 8 */
  public B maxConnections(int maxConnections) {
    if (maxConnections <= 0) throw new IllegalArgumentException("maxConnections <= 0");
    this.poolLocalSize = maxConnections;
    return (B) this;
  }

  /** Will throw an exception on startup if authentication fails. No default. */
  public B username(@Nullable String username) {
    this.username = username;
    return (B) this;
  }

  /** Will throw an exception on startup if authentication fails. No default. */
  public B password(@Nullable String password) {
    this.password = password;
    return (B) this;
  }

  /** Use ssl for connection. Defaults to false. */
  public B useSsl(boolean useSsl) {

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Set a positive pool size, e.g. maxConnections(8) (the default)
2. Fix property mapping so unset values fall back to 8 instead of 0
3. For low-throughput setups use a small positive value like 2 rather than 0

Example fix

# before
zipkin.storage.cassandra.max-connections=0

# after
zipkin.storage.cassandra.max-connections=8

int maxConnections = config.getInt("maxConnections", 8);
if (maxConnections <= 0) throw new IllegalArgumentException("maxConnections must be positive");

When it happens

Trigger: Calling maxConnections(0) or a negative value, or binding an unset optional property (zipkin.storage.cassandra.max-connections) that unboxes to int 0.

Common situations: Property omitted in config and defaulted to 0 by a mapping layer; operators tuning pool size down for memory and overshooting; integer truncation of a fractional computed value to 0.

Related errors

• maxTraceCols <= 0
• %s has an empty host
• concurrency < 1
• rate should be between 0 and 1: was {}
• clientProps is empty

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/f7fe684fa98191e3. Report an issue: GitHub.