apache/druid · error · IllegalArgumentException

maxStringBytes must be greater than 0

Error message

maxStringBytes must be greater than 0

What it means

StringAnyAggregatorFactory's constructor validates that the optional maxStringBytes parameter, when supplied, is non-negative. If a negative value is passed, Preconditions-style validation throws IAE("maxStringBytes must be greater than 0") to fail fast at aggregator construction rather than at query time.

Source

Thrown at processing/src/main/java/org/apache/druid/query/aggregation/any/StringAnyAggregatorFactory.java:66

  private static final Comparator<String> VALUE_COMPARATOR = Comparator.nullsFirst(Comparator.naturalOrder());

  private final String fieldName;
  private final String name;
  private final int maxStringBytes;
  private final boolean aggregateMultipleValues;

  @JsonCreator
  public StringAnyAggregatorFactory(
      @JsonProperty("name") String name,
      @JsonProperty("fieldName") final String fieldName,
      @JsonProperty("maxStringBytes") Integer maxStringBytes,
      @JsonProperty("aggregateMultipleValues") @Nullable final Boolean aggregateMultipleValues
  )
  {
    Preconditions.checkNotNull(name, "Must have a valid, non-null aggregator name");
    Preconditions.checkNotNull(fieldName, "Must have a valid, non-null fieldName");
    if (maxStringBytes != null && maxStringBytes < 0) {
      throw new IAE("maxStringBytes must be greater than 0");
    }
    this.name = name;
    this.fieldName = fieldName;
    this.maxStringBytes = maxStringBytes == null
                          ? StringFirstAggregatorFactory.DEFAULT_MAX_STRING_SIZE
                          : maxStringBytes;
    this.aggregateMultipleValues = aggregateMultipleValues == null ? true : aggregateMultipleValues;
  }

  @Override
  public Aggregator factorize(ColumnSelectorFactory metricFactory)
  {
    return new StringAnyAggregator(metricFactory.makeColumnValueSelector(fieldName), maxStringBytes, aggregateMultipleValues);
  }

  @Override
  public BufferAggregator factorizeBuffered(ColumnSelectorFactory metricFactory)
  {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set maxStringBytes to a positive integer (or omit it to use StringFirstAggregatorFactory.DEFAULT_MAX_STRING_SIZE)
2. Check the aggregation spec JSON for a negative maxStringBytes value and correct it
3. If maxStringBytes is supplied programmatically, clamp with Math.max(0, maxStringBytes) before constructing

Example fix

// before
{"type":"any", "name":"any_col", "fieldName":"col", "maxStringBytes":-1}
// after
{"type":"any", "name":"any_col", "fieldName":"col", "maxStringBytes":1024}

if (spec.has("maxStringBytes") && spec.getIntValue("maxStringBytes") < 0) {
    throw new IllegalArgumentException("maxStringBytes must be >= 0");
}

When it happens

Trigger: Constructing a StringAnyAggregatorFactory (directly or via JSON ingestion/query spec deserialization) with maxStringBytes set to a negative number, e.g. {"type":"any","fieldName":"col","maxStringBytes":-1}. Note the check allows 0 (maxStringBytes < 0), so only strictly negative values throw.

Common situations: Copy-pasted ingestion spec with a mistyped or miscomputed maxStringBytes; a templated config where a variable resolved to a negative value; manual JSON editing of an aggregator spec.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• maxStringBytes must be greater than 0
• Aggregation [%s] does not support column [%s] of type [%s].
• Must have a valid, non-null aggregator name
• Parameter fieldName must be specified
• AggregatorFactoryNotMergeableException(this, other)

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/3474411b236eae05. Report an issue: GitHub.