apache/druid · error · IllegalArgumentException

Unsupported segment graularity. Please use an equivalent of

Error message

Unsupported segment graularity. Please use an equivalent of these granularities: %s.

What it means

CatalogUtils.validateGranularity rejects granularity values that are not one of Druid's standard GranularityTypes (second through year, etc.). Druid segments require a standard granularity; arbitrary custom periods are not accepted for segment partitioning.

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/CatalogUtils.java:294

        Object value = entry.getValue();
        final PropertyDefn<?> propDefn = properties.get(entry.getKey());
        if (propDefn != null) {
          value = propDefn.merge(merged.get(entry.getKey()), entry.getValue());
        }
        merged.put(entry.getKey(), value);
      }
    }
    return merged;
  }

  public static void validateGranularity(final String value)
  {
    if (value == null) {
      return;
    }
    final Granularity granularity = asDruidGranularity(value);
    if (!GranularityType.isStandard(granularity)) {
      throw new IAE(
          "Unsupported segment graularity. "
          + "Please use an equivalent of these granularities: %s.",
          Arrays.stream(GranularityType.values())
                .filter(granularityType -> !granularityType.equals(GranularityType.NONE))
                .map(Enum::name)
                .map(StringUtils::toLowerCase)
                .collect(Collectors.joining(", "))
      );
    }
  }

  public static int findColumn(List<ColumnSpec> columns, String colName)
  {
    for (int i = 0; i < columns.size(); i++) {
      if (columns.get(i).name().equals(colName)) {
        return i;
      }
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

Change the granularity to a standard value: second, minute, fifteen_minute, thirty_minute, hour, day, week, month, quarter, or year.
If a custom bucket is required, partition/rollup upstream before ingest and keep segment granularity standard.
Check for typos or a period string (e.g. "P1MT6H") that is not equivalent to a standard granularity.

Example fix

// before
"segmentGranularity": {"type": "period", "period": "PT37M"}
// after
"segmentGranularity": "hour"

Defensive patterns

Strategy: validation

Validate before calling

Granularity g = CatalogUtils.asDruidGranularity(value);
if (g != null && !GranularityType.isStandard(g)) {
  throw new IllegalArgumentException("segmentGranularity must be a standard Druid granularity");
}

Type guard

boolean isStandardGranularity(String name) {
  try { return GranularityType.isStandard(GranularityType.fromString(name).getDefaultGranularity()); }
  catch (IllegalArgumentException e) { return false; }
}

Try / catch

try { CatalogUtils.validateGranularity(value); } catch (IllegalArgumentException e) { // surface list of allowed granularities from e.getMessage() to the user }

Prevention

Only use the named standard granularities (second..year) for segment granularity.
Do custom bucketing upstream of Druid; keep segment granularity standard.
Reject period-string configs like PT37M at config-validation time.

When it happens

Trigger: Setting a catalog/table segment granularity property to a non-standard granularity such as a custom Period (e.g. PT37M), a derived granularity object, or NONE. Reached via validateGranularity when asDruidGranularity yields a non-standard granularity.

Common situations: Users configure a custom retention/rollup period like 10-minute or 37-minute granularity; config generated programmatically builds a Granularity from a period string that doesn't match a standard type; typo in a granularity name resolves to an odd period.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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