apache/druid · error · IllegalArgumentException

Unknown residualFilterMode

Error message

Unknown residualFilterMode: %s. Valid values are: ignore, fail

What it means

Validation in ResidualFilterMode.fromString(): the residualFilterMode input spec property contained a value other than 'ignore' or 'fail' (case-insensitive). The parser iterates the enum values and, finding no match, rejects the input reader configuration; set the property to one of the two valid values.

Solutions

  1. Set residualFilterMode to `ignore` or `fail` (case-insensitive).
  2. Fix typos and confirm the property value reaches this enum.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java:67 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at extensions-contrib/druid-iceberg-extensions/src/main/java/org/apache/druid/iceberg/input/ResidualFilterMode.java:67

  ResidualFilterMode(String value)
  {
    this.value = value;
  }

  @JsonValue
  public String getValue()
  {
    return value;
  }

  public static ResidualFilterMode fromString(String value)
  {
    for (ResidualFilterMode mode : values()) {
      if (mode.value.equalsIgnoreCase(value)) {
        return mode;
      }
    }
    throw new IllegalArgumentException(
        "Unknown residualFilterMode: " + value + ". Valid values are: ignore, fail"
    );
  }
}

View on GitHub (pinned to 9b90983fd2)