apache/druid · error · IllegalArgumentException (IAE)

valid values for maxListingLength are between [%d, %d]

Error message

valid values for maxListingLength are between [%d, %d]

What it means

S3InputDataConfig.setMaxListingLength validates that maxListingLength lies within [MAX_LISTING_LENGTH_MIN, MAX_LISTING_LENGTH_MAX] and throws IAE otherwise. This property caps the page size of S3 list operations (e.g. task log listing).

Source

Thrown at extensions-core/s3-extensions/src/main/java/org/apache/druid/storage/s3/S3InputDataConfig.java:58

   * https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html#API_DeleteObjects_RequestSyntax
   */
  @VisibleForTesting
  static final int MAX_LISTING_LENGTH_MAX = 1000;

  /**
   * The maximum number of input files matching a given prefix to retrieve
   * or delete from Amazon S3 at a time.
   */
  @JsonProperty
  @Min(MAX_LISTING_LENGTH_MIN)
  @Max(MAX_LISTING_LENGTH_MAX)
  private int maxListingLength = MAX_LISTING_LENGTH_MAX;

  @VisibleForTesting
  public void setMaxListingLength(int maxListingLength)
  {
    if (maxListingLength < MAX_LISTING_LENGTH_MIN || maxListingLength > MAX_LISTING_LENGTH_MAX) {
      throw new IAE("valid values for maxListingLength are between [%d, %d]", MAX_LISTING_LENGTH_MIN,
                    MAX_LISTING_LENGTH_MAX
      );
    }
    this.maxListingLength = maxListingLength;
  }

  public int getMaxListingLength()
  {
    return maxListingLength;
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set maxListingLength within the documented min/max range (e.g. 100..1000).
2. Remove the property to use the default (MAX_LISTING_LENGTH_MAX).
3. Check for unit mistakes (e.g. using byte values instead of page size).

Example fix

// before
druid.storage.s3.maxListingLength=0
// after
druid.storage.s3.maxListingLength=500

int v = Integer.parseInt(props.getProperty("druid.storage.s3.maxListingLength"));
if (v < 1 || v > 1000) throw new IllegalArgumentException("maxListingLength out of range: " + v);

When it happens

Trigger: Setting druid.storage.s3.maxListingLength (or calling the setter, e.g. from S3TaskLogs.getS3TaskLogs configuration) to a value below the minimum or above the maximum.

Common situations: Copy-pasted config with 0 or negative value; attempts to set an arbitrarily large page size to reduce list calls; typos like 1000000 exceeding the allowed max.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Target S3 bucket is not specified
• Target S3 baseKey is not specified
• Cannot set kafka property [group.id]. Property is randomly g
• Cannot set kafka property [auto.offset.reset]. Property will
• Cannot set kafka property [enable.auto.commit]. Property wil

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