apache/druid · error · IllegalArgumentException

[%s] is an invalid granularity string.

Error message

[%s] is an invalid granularity string.

What it means

Thrown by CatalogUtils.asDruidGranularity when a granularity string cannot be parsed either as a named Druid granularity (GranularityType/fromString throws IllegalArgumentException) nor as an ISO-8601 period (new Period(value) also throws IllegalArgumentException). It signals the catalog table property holds an unparseable granularity value.

Source

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

   * are either the usual descriptive strings (in any case), or an ISO period.
   * For the odd interval, the interval name is also accepted (for the other
   * intervals, the interval name is the descriptive string).
   */
  public static Granularity asDruidGranularity(@Nonnull String value)
  {
    if (value.equalsIgnoreCase(DatasourceDefn.ALL_GRANULARITY)) {
      return Granularities.ALL;
    }
    Granularity granularity;
    try {
      granularity = Granularity.fromString(value);
    }
    catch (IllegalArgumentException e) {
      try {
        granularity = new PeriodGranularity(new Period(value), null, null);
      }
      catch (IllegalArgumentException e2) {
        throw new IAE("[%s] is an invalid granularity string.", value);
      }
    }

    return granularity;
  }

  /**
   * {@code String}-to-{@code List<String>} conversion. The string can contain zero items,
   * one items, or a list. The list items are separated by a comma and optional
   * whitespace.
   */
  public static List<String> stringToList(String value)
  {
    if (value == null) {
      return null;
    }
    return Arrays.asList(value.split(",\\s*"));
  }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Use a standard granularity name (e.g. 'day') or a valid ISO-8601 period (e.g. 'P1D', 'PT6H')
2. Validate the string with new Period(value) or GranularityType.fromString before persisting it
3. Fix the offending catalog table property and retry the operation

Example fix

// before
"granularity": "1 day"
// after
"granularity": "P1D"

boolean valid = false;
try {
  org.apache.druid.java.util.common.granularity.GranularityType.fromString(value);
  valid = true;
} catch (IllegalArgumentException ignore) {
  try { new org.joda.time.Period(value); valid = true; }
  catch (IllegalArgumentException ignore2) { }
}
if (!valid) throw new IllegalArgumentException("Bad granularity: " + value);

try {
  Granularity g = CatalogUtils.asDruidGranularity(value);
} catch (IllegalArgumentException e) {
  log.error("Granularity '{}' is neither a named granularity nor an ISO period", value);
}

When it happens

Trigger: Setting a table's granularity property to a string that is neither a standard name (second, minute, hour, day, week, month, quarter, year, all) nor a valid ISO-8601 period such as PT1H or P1D - e.g. '1day', 'hourly', '1 hour', or an empty string.

Common situations: Users authoring catalog/table specs by hand assuming human-friendly names like 'daily' work, SQL catalog updates with typos, tool-generated specs emitting locale-formatted durations.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Unsupported segment graularity. Please use an equivalent of
• An external S3 table with a format must also provide the cor
• Provide either the %s property, or one of the S3 input sourc
• The %s property cannot be provided when the %s property is s
• S3 external table defines the %s property. The table functio

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