apache/druid · error · IllegalArgumentException

Unknown type[%s] for dimension[%s]

Error message

Unknown type[%s] for dimension[%s]

What it means

LegacyDimensionSpec.convertValue() builds the spec from a legacy JSON 'dimension' field that must be either a plain string or a map containing the dimension name as a key. Any other JSON type (number, array, etc.) cannot be converted, so Druid throws this IAE during deserialization.

Source

Thrown at processing/src/main/java/org/apache/druid/query/dimension/LegacyDimensionSpec.java:40

import com.fasterxml.jackson.annotation.JsonCreator;
import org.apache.druid.java.util.common.IAE;

import java.util.Map;

/**
 */
public class LegacyDimensionSpec extends DefaultDimensionSpec
{
  private static String convertValue(Object dimension, String name)
  {
    final String retVal;

    if (dimension instanceof String) {
      retVal = (String) dimension;
    } else if (dimension instanceof Map) {
      retVal = (String) ((Map) dimension).get(name);
    } else {
      throw new IAE("Unknown type[%s] for dimension[%s]", dimension.getClass(), dimension);
    }

    return retVal;
  }

  @JsonCreator
  public LegacyDimensionSpec(Object dimension)
  {
    super(convertValue(dimension, "dimension"), convertValue(dimension, "outputName"));
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Fix the query JSON so 'dimension' is a plain string like "dimName"
2. If a map form is intended, use {"dimName": "outputAlias"} keyed by the spec's name
3. Replace the legacy spec with DefaultDimensionSpec or ExtractionDimensionSpec in current Druid

Example fix

// before
{"type":"legacy","dimension":42,"outputName":"d"}
// after
{"type":"legacy","dimension":"dimName","outputName":"d"}

if (!(dimension instanceof String) && !(dimension instanceof Map)) {
  throw new IllegalArgumentException("dimension must be String or Map");
}

boolean ok = dim != null && (dim instanceof String || dim instanceof Map);

try {
  spec = jsonMapper.readValue(json, LegacyDimensionSpec.class);
} catch (IllegalArgumentException | JsonProcessingException e) {
  log.error("Bad legacy dimension spec: %s", e.getMessage());
}

When it happens

Trigger: Deserializing a legacy dimension spec where 'dimension' is neither a String nor a Map, e.g. numeric or nested-array JSON; programmatically constructing LegacyDimensionSpec with a non-String/non-Map value.

Common situations: Hand-edited native JSON queries from old Druid versions; migration of saved queries where the dimension field was corrupted or transformed by another tool.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Failed to deserialize a DB object
• Invalid JSON inside unknown key:
• Invalid format specification
• Failed to deserialize authorizer role, ignoring: %s
• unknown event type [%s]

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