openzipkin/zipkin · error · IllegalArgumentException

indexFetchMultiplier <= 0

Error message

indexFetchMultiplier <= 0

What it means

Thrown by CassandraStorageBuilder.indexFetchMultiplier(int) when the value is zero or negative. This multiplier decides how many index rows to fetch relative to the user's query limit (default 3), over-fetching to compensate for duplicate trace ids in Cassandra indexes. Zero or negative would make the fetch useless, so the builder rejects it.

Source

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

  public B maxTraceCols(int maxTraceCols) {
    if (maxTraceCols <= 0) throw new IllegalArgumentException("maxTraceCols <= 0");
    this.maxTraceCols = maxTraceCols;
    return (B) this;
  }

  /**
   * How many more index rows to fetch than the user-supplied query limit. Defaults to 3.
   *
   * <p>Backend requests will request {@link QueryRequest#limit()} times this factor rows from
   * Cassandra indexes in attempts to return {@link QueryRequest#limit()} traces.
   *
   * <p>Indexing in cassandra will usually have more rows than trace identifiers due to factors
   * including table design and collection implementation. As there's no way to DISTINCT out
   * duplicates server-side, this over-fetches client-side when {@code indexFetchMultiplier} &gt;
   * 1.
   */
  public B indexFetchMultiplier(int indexFetchMultiplier) {
    if (indexFetchMultiplier <= 0) throw new IllegalArgumentException("indexFetchMultiplier <= 0");
    this.indexFetchMultiplier = indexFetchMultiplier;
    return (B) this;
  }
}

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Use a positive multiplier, typically the default 3 (or >= 1 if you accept fewer duplicate traces deduped).
2. Validate any config-sourced multiplier for > 0 before passing it to the builder.

Example fix

// before
.indexFetchMultiplier(0)

// after
.indexFetchMultiplier(3)

int m = config.getInt("cassandra.index-fetch-multiplier", 3);
if (m <= 0) throw new IllegalArgumentException("indexFetchMultiplier must be > 0, got " + m);
builder.indexFetchMultiplier(m);

When it happens

Trigger: Calling indexFetchMultiplier(0) or a negative value on CassandraStorage.newBuilder(); deriving the multiplier from arithmetic that underflows to 0 or a negative number.

Common situations: Tuning configs copied from blog posts with a value of 0 meaning 'no over-fetch'; properties files where the key is misspelled and a 0 default is used.

Related errors

• maxTraceCols <= 0
• concurrency < 1
• clientProps is empty
• consumerProps is empty
• Start bucket ({startBucket}) > end bucket ({endBucket})

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