apache/superset · error · Error

Spatial configuration is required for Scatter charts

Error message

Spatial configuration is required for Scatter charts

What it means

Thrown by the deck.gl Scatter layer's buildQuery when the spatial form field is absent. A scatter point is placed entirely by its spatial configuration (latlong columns, delimited lon/lat column, or geohash), so buildQuery refuses to proceed without it. Configuration-time guard, raised before getSpatialColumns or any SQL assembly.

Source

Thrown at superset-frontend/plugins/preset-chart-deckgl/src/layers/Scatter/buildQuery.ts:57

  point_radius_fixed?:
    | string // Legacy format: metric name directly
    | {
        type?: 'fix' | 'metric';
        value?: QueryFormMetric | number;
      };
  multiplier?: number;
  point_unit?: string;
  min_radius?: number;
  max_radius?: number;
  color_picker?: { r: number; g: number; b: number; a: number };
  dimension?: string;
}

export default function buildQuery(formData: DeckScatterFormData) {
  const { spatial, point_radius_fixed, dimension, tooltip_contents } = formData;

  if (!spatial) {
    throw new Error('Spatial configuration is required for Scatter charts');
  }

  return buildQueryContext(formData, {
    buildQuery: (baseQueryObject: QueryObject) => {
      const spatialColumns = getSpatialColumns(spatial);
      let columns = [...(baseQueryObject.columns || []), ...spatialColumns];

      if (dimension) {
        columns.push(dimension);
      }

      columns = addTooltipColumnsToQuery(columns, tooltip_contents);

      // Only add metric if point_radius_fixed is a metric type
      const isMetric = isMetricValue(point_radius_fixed);
      // Extract metric value: legacy string format or object with metric value
      const rawValue =
        typeof point_radius_fixed === 'string'

View on GitHub (pinned to f4587218dd)

Solutions

1. Open the Scatter chart in Explore and configure the spatial control (latlong / delimited / geohash), then save.
2. Confirm the bound columns still exist in the dataset; rebind after schema changes.
3. Populate formData.spatial before calling buildQuery in code.

Example fix

// before
buildQuery(formData); // spatial undefined

// after
if (!formData.spatial) {
  throw new Error('Configure the spatial control first');
}
buildQuery(formData);

if (!formData.spatial) {
  throw new Error('Configure the spatial control before querying');
}
buildQuery(formData);

const hasSpatial = (fd: DeckScatterFormData): boolean => Boolean(fd.spatial?.type);

try { buildQuery(formData); } catch (e) { if (e.message.includes('Spatial configuration')) showExploreWarning(e.message); else throw e; }

When it happens

Trigger: Building the query for a Deck.gl Scatter chart whose spatial control is unset — newly added chart, imported dashboard params missing 'spatial', or a query context constructed without the key.

Common situations: Chart saved half-configured; spatial columns removed from the dataset; switching a chart between spatial encodings leaving an empty object; programmatic chart creation with partial params.

Related errors

• Start and end spatial configurations are required for Arc ch
• Spatial configuration is required for this chart
• GeoJSON column is required for GeoJSON charts
• Line column is required for Path charts
• Polygon column is required for Polygon charts

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/847641a6bffa24e2. Report an issue: GitHub.