apache/druid · error · IllegalArgumentException

Cannot specify DESC clustering key

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.

Solutions

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

Example fix

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

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

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

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

• Cannot hide column
• Cannot coerce value [ ] of type [ ] for column [ ] to
• Cannot handle dataSource
• Catalog definition for the
• Column name is required

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

Appendix: 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)