openzipkin/zipkin · error · IllegalArgumentException

autocompleteCardinality <= 0

Error message

autocompleteCardinality <= 0

What it means

CassandraStorageBuilder.autocompleteCardinality(int) throws IllegalArgumentException ('autocompleteCardinality <= 0') when a non-positive cardinality limit is configured for autocomplete values. This bounds how many distinct values per autocomplete key are kept; zero or negative would mean no values could ever be stored, so the builder fails fast.

Source

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

    this.searchEnabled = searchEnabled;
    return (B) this;
  }

  @Override public B autocompleteKeys(List<String> keys) {
    if (keys == null) throw new NullPointerException("keys == null");
    this.autocompleteKeys = Set.copyOf(keys);
    return (B) this;
  }

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

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

  /**
   * Comma separated list of host addresses part of Cassandra cluster. You can also specify a custom
   * port with 'host:port'. Defaults to localhost on port 9042 *
   */
  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.

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Set a positive cardinality, e.g. zipkin.storage.cassandra.autocomplete-cardinality=20000 (the documented default)
2. Fix config mapping so unset properties fall back to the default instead of 0
3. Only tune this when autocomplete value sets are very large

Example fix

# before
zipkin.storage.cassandra.autocomplete-cardinality=0

# after
zipkin.storage.cassandra.autocomplete-cardinality=20000

int cardinality = config.getInt("autocompleteCardinality", 20000);
if (cardinality <= 0) throw new IllegalArgumentException("autocompleteCardinality must be positive");

When it happens

Trigger: Calling autocompleteCardinality(0) or a negative number, or wiring an optional config property (zipkin.storage.cassandra.autocomplete-cardinality) that resolved to 0 because it was unset.

Common situations: Property omitted and mapped to Java int default 0; operators misreading the setting as a boolean/percentage; copy-paste from another storage module with different semantics.

Related errors

• autocompleteTtl <= 0
• key == null
• keys == null
• contactPoints == null
• maxConnections <= 0

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