apache/druid · error · IllegalArgumentException

Cannot specify DESC clustering key [%s]. Only ASC is support

Error message

Cannot specify DESC clustering key [%s]. Only ASC is supported.

What it means

Validation guard in the ClusterKeysDefn property definition for datasource table specs: clustering currently only supports ascending sort, and a ClusterKeySpec with desc=true would produce a clustering layout Druid cannot maintain. It fires when a datasource definition (or its JSON spec) declares a clustering column with descending order; flip the key to ascending (or drop it) when configuring clusterBy in the table spec.

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/table/DatasourceDefn.java:180

    public ClusterKeysDefn()
    {
      super(
          CLUSTER_KEYS_PROPERTY,
          "ClusterKeySpec list",
          new TypeReference<>() {}
      );
    }

    @Override
    public void validate(Object value, ObjectMapper jsonMapper)
    {
      if (value == null) {
        return;
      }
      List<ClusterKeySpec> clusterKeys = decode(value, jsonMapper);
      for (ClusterKeySpec clusterKey : clusterKeys) {
        if (clusterKey.desc()) {
          throw new IAE(
              StringUtils.format("Cannot specify DESC clustering key [%s]. Only ASC is supported.", clusterKey)
          );
        }
      }
    }
  }

  public static class ProjectionsDefn extends ModelProperties.TypeRefPropertyDefn<List<DatasourceProjectionMetadata>>
  {
    public static final TypeReference<List<DatasourceProjectionMetadata>> TYPE_REF = new TypeReference<>() {};

    public ProjectionsDefn()
    {
      super(PROJECTIONS_KEYS_PROPERTY, "DatasourceProjectionMetadata list", TYPE_REF);
    }
  }

  public static class BaseTableDefn extends ModelProperties.TypeRefPropertyDefn<DatasourceBaseTableMetadata>

View on GitHub (pinned to 9b90983fd2)

Solutions

Remove the DESC direction so each clustering key defaults to ascending.
Explicitly set desc:false in each ClusterKeySpec entry.
Reorder columns rather than reversing directions if ordering semantics matter.
Update tooling/templates that emit DESC clustering keys.

Example fix

// before
"clusteringColumns": [{"column":"region","desc":true}]
// after
"clusteringColumns": [{"column":"region","desc":false}]

Defensive patterns

Strategy: validation

Validate before calling

for (ClusterKeySpec key : spec.getClusteringColumns()) {
  if (key.desc()) throw new IllegalArgumentException("DESC clustering not supported: " + key);
}

Try / catch

try { saveSpec(spec); } catch (IAE e) { if (e.getMessage().contains("Only ASC is supported")) { spec.getClusteringColumns().forEach(k -> k.setDesc(false)); saveSpec(spec); } }

Prevention

Always use ascending order for clustering keys
Scrub direction flags when migrating specs from other systems
Disable direction selection for clustering in custom tooling
Prefer reordering columns over reversing sort direction

When it happens

Trigger: Creating or updating a datasource whose clusteringColumns property contains a key with desc=true; validate() decodes the ClusterKeySpec list and throws on the first descending key.

Common situations: Users copying ORDER BY-style specs with DESC; generating clustering keys from a UI that allows direction selection; migrating specs written for other systems that permit descending clustering.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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