apache/druid · error · IllegalStateException

Spatial dimension value must be in an array!

Error message

Spatial dimension value must be in an array!

What it means

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.

Solutions

1. 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)
2. Rename the raw multi-valued field and create the spatial dimension via a transform that joins coordinates into one array-valued field
3. Check that the spatial dim name does not collide with an existing multi-valued dimension in the row

Example fix

// before (input)
{"lat": 37.7, "lon": -122.4, "geo": "37.7,-122.4"} with geo also listed as dim
// after
"spatialDimensions": [{"dimName": "geo", "dims": ["lat", "lon"]}] and geo not ingested as a normal dimension

List<String> v = row.getDimension(spatialDimName);
if (v != null && v.size() != 1) throw new IllegalArgumentException("Spatial value must be single array");

try { transformer.transform(row); } catch (ISE e) { if (e.getMessage().contains("must be in an array")) { /* fix input encoding */ } throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Attempt to add row to swapped-out sink for segment
• authResult.getErrorMessage()
• Bloom filter aggregators are query-time only
• Can't find previous segmentIds for sequence
• Can't find previously allocated segmentId

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/incremental/SpatialDimensionRowTransformer.java:163

      {
        return row.toString();
      }

      @Override
      public int compareTo(Row o)
      {
        return getTimestamp().compareTo(o.getTimestamp());
      }
    };

    for (Map.Entry<String, SpatialDimensionSchema> entry : spatialDimensionMap.entrySet()) {
      final String spatialDimName = entry.getKey();
      final SpatialDimensionSchema spatialDim = entry.getValue();

      List<String> dimVals = row.getDimension(spatialDimName);
      if (dimVals != null && !dimVals.isEmpty()) {
        if (dimVals.size() != 1) {
          throw new ISE("Spatial dimension value must be in an array!");
        }
        if (isJoinedSpatialDimValValid(dimVals.get(0))) {
          spatialLookup.put(spatialDimName, dimVals);
          finalDims.add(spatialDimName);
        }
      } else {
        List<String> spatialDimVals = new ArrayList<>();
        for (String dim : spatialDim.getDims()) {
          List<String> partialDimVals = row.getDimension(dim);
          if (isSpatialDimValsValid(partialDimVals)) {
            spatialDimVals.addAll(partialDimVals);
          }
        }

        if (spatialDimVals.size() == spatialDim.getDims().size()) {
          spatialLookup.put(spatialDimName, Collections.singletonList(JOINER.join(spatialDimVals)));
          finalDims.add(spatialDimName);
        }

View on GitHub (pinned to 9b90983fd2)