{"record":{"id":"5c8926c5029c184f","repo":"apache/druid","slug":"spatial-dimension-value-must-be-in-an-array","errorCode":null,"errorMessage":"Spatial dimension value must be in an array!","messagePattern":"Spatial dimension value must be in an array!","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/segment/incremental/SpatialDimensionRowTransformer.java","lineNumber":163,"sourceCode":"      {\n        return row.toString();\n      }\n\n      @Override\n      public int compareTo(Row o)\n      {\n        return getTimestamp().compareTo(o.getTimestamp());\n      }\n    };\n\n    for (Map.Entry<String, SpatialDimensionSchema> entry : spatialDimensionMap.entrySet()) {\n      final String spatialDimName = entry.getKey();\n      final SpatialDimensionSchema spatialDim = entry.getValue();\n\n      List<String> dimVals = row.getDimension(spatialDimName);\n      if (dimVals != null && !dimVals.isEmpty()) {\n        if (dimVals.size() != 1) {\n          throw new ISE(\"Spatial dimension value must be in an array!\");\n        }\n        if (isJoinedSpatialDimValValid(dimVals.get(0))) {\n          spatialLookup.put(spatialDimName, dimVals);\n          finalDims.add(spatialDimName);\n        }\n      } else {\n        List<String> spatialDimVals = new ArrayList<>();\n        for (String dim : spatialDim.getDims()) {\n          List<String> partialDimVals = row.getDimension(dim);\n          if (isSpatialDimValsValid(partialDimVals)) {\n            spatialDimVals.addAll(partialDimVals);\n          }\n        }\n\n        if (spatialDimVals.size() == spatialDim.getDims().size()) {\n          spatialLookup.put(spatialDimName, Collections.singletonList(JOINER.join(spatialDimVals)));\n          finalDims.add(spatialDimName);\n        }","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/segment/incremental/SpatialDimensionRowTransformer.java#L145-L181","documentation":"During row transformation, a spatial dimension's value list (from row.getDimension) must contain exactly one entry representing the array of coordinates. If it has more than one element the transformer cannot interpret it as a single spatial value array and throws this ISE.","triggerScenarios":"A row provides a spatial dimension with multiple values (dimVals.size() != 1), e.g. the spatial field was sent as separate repeated dimension values rather than a single array/JSON list.","commonSituations":"Input JSON like {\"geo\": [1.0, 2.0]} flattened by a parser into two dimension values; CSV parsers splitting coordinates into multiple values; feeding spatial dims as ordinary multi-valued dimensions.","solutions":["Ensure the input parser yields the spatial value as a single value containing an array (e.g. use the correct parseSpec/JSON parsing for that field)","Rename the raw multi-valued field and create the spatial dimension via a transform that joins coordinates into one array-valued field","Check that the spatial dim name does not collide with an existing multi-valued dimension in the row"],"exampleFix":"// before (input)\n{\"lat\": 37.7, \"lon\": -122.4, \"geo\": \"37.7,-122.4\"} with geo also listed as dim\n// after\n\"spatialDimensions\": [{\"dimName\": \"geo\", \"dims\": [\"lat\", \"lon\"]}] and geo not ingested as a normal dimension","handlingStrategy":"validation","validationCode":"List<String> v = row.getDimension(spatialDimName);\nif (v != null && v.size() != 1) throw new IllegalArgumentException(\"Spatial value must be single array\");","typeGuard":null,"tryCatchPattern":"try { transformer.transform(row); } catch (ISE e) { if (e.getMessage().contains(\"must be in an array\")) { /* fix input encoding */ } throw e; }","preventionTips":["Verify parser output shape for spatial fields","Avoid name collisions between dims and spatial dims"],"tags":["spatial","row-format","ingestion"],"backgroundTag":"invalid-argument-format","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}