{"record":{"id":"83124a206f8c29e8","repo":"apache/druid","slug":"unknown-type-s-for-dimension-s","errorCode":null,"errorMessage":"Unknown type[%s] for dimension[%s]","messagePattern":"Unknown type\\[(.+?)\\] for dimension\\[(.+?)\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/query/dimension/LegacyDimensionSpec.java","lineNumber":40,"sourceCode":"import com.fasterxml.jackson.annotation.JsonCreator;\nimport org.apache.druid.java.util.common.IAE;\n\nimport java.util.Map;\n\n/**\n */\npublic class LegacyDimensionSpec extends DefaultDimensionSpec\n{\n  private static String convertValue(Object dimension, String name)\n  {\n    final String retVal;\n\n    if (dimension instanceof String) {\n      retVal = (String) dimension;\n    } else if (dimension instanceof Map) {\n      retVal = (String) ((Map) dimension).get(name);\n    } else {\n      throw new IAE(\"Unknown type[%s] for dimension[%s]\", dimension.getClass(), dimension);\n    }\n\n    return retVal;\n  }\n\n  @JsonCreator\n  public LegacyDimensionSpec(Object dimension)\n  {\n    super(convertValue(dimension, \"dimension\"), convertValue(dimension, \"outputName\"));\n  }\n}\n","sourceCodeStart":22,"sourceCodeEnd":52,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/dimension/LegacyDimensionSpec.java#L22-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"Hand-edited native JSON queries from old Druid versions; migration of saved queries where the dimension field was corrupted or transformed by another tool.","solutions":["Fix the query JSON so 'dimension' is a plain string like \"dimName\"","If a map form is intended, use {\"dimName\": \"outputAlias\"} keyed by the spec's name","Replace the legacy spec with DefaultDimensionSpec or ExtractionDimensionSpec in current Druid"],"exampleFix":"// before\n{\"type\":\"legacy\",\"dimension\":42,\"outputName\":\"d\"}\n// after\n{\"type\":\"legacy\",\"dimension\":\"dimName\",\"outputName\":\"d\"}","handlingStrategy":"validation","validationCode":"if (!(dimension instanceof String) && !(dimension instanceof Map)) {\n  throw new IllegalArgumentException(\"dimension must be String or Map\");\n}","typeGuard":"boolean ok = dim != null && (dim instanceof String || dim instanceof Map);","tryCatchPattern":"try {\n  spec = jsonMapper.readValue(json, LegacyDimensionSpec.class);\n} catch (IllegalArgumentException | JsonProcessingException e) {\n  log.error(\"Bad legacy dimension spec: %s\", e.getMessage());\n}","preventionTips":["Always serialize the legacy 'dimension' field as a string or {name: alias} map","Validate query JSON against the Druid schema before submission","Migrate legacy specs to DefaultDimensionSpec/ExtractionDimensionSpec"],"tags":["json","deserialization","dimension-spec"],"backgroundTag":"invalid-argument-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}