apache/superset · error · Error

Spatial configuration is required for this chart

Error message

Spatial configuration is required for this chart

What it means

Thrown by buildSpatialQuery in the deck.gl spatial utilities when formData.spatial is absent. This helper builds the query context for spatially-driven layers (it later delegates to getSpatialColumns), and without a spatial configuration there are no coordinate columns to request, so it refuses up front.

Source

Thrown at superset-frontend/plugins/preset-chart-deckgl/src/layers/spatialUtils.ts:123

  filters: QueryObjectFilterClause[],
): QueryObjectFilterClause[] {
  if (!spatial) return filters;

  const spatialColumns = getSpatialColumns(spatial);
  const nullFilters: QueryObjectFilterClause[] = spatialColumns.map(column => ({
    col: column,
    op: 'IS NOT NULL',
    val: null,
  }));

  return [...filters, ...nullFilters];
}

export function buildSpatialQuery(formData: SpatialFormData) {
  const { spatial, size: metric, tooltip_contents } = formData;

  if (!spatial) {
    throw new Error(`Spatial configuration is required for this chart`);
  }
  return buildQueryContext(formData, {
    buildQuery: baseQueryObject => {
      const spatialColumns = getSpatialColumns(spatial);
      let columns = [...(baseQueryObject.columns || []), ...spatialColumns];
      const metrics = metric ? [metric] : [];

      columns = addTooltipColumnsToQuery(columns, tooltip_contents);

      const filters = addSpatialNullFilters(
        spatial,
        ensureIsArray(baseQueryObject.filters || []),
      );

      const orderby = metric
        ? normalizeOrderBy({ orderby: [[metric, false]] }).orderby
        : baseQueryObject.orderby;

View on GitHub (pinned to f4587218dd)

Solutions

1. Configure the chart's spatial control in Explore (latlong/delimited/geohash plus its column) and save.
2. Verify saved chart params include a populated spatial object; repair via PUT /api/v1/chart/{id}.
3. Guard in code: check formData.spatial before invoking buildSpatialQuery and surface a config prompt instead.

Example fix

// before
buildSpatialQuery({ ...formData }); // spatial undefined

// after
if (!formData.spatial) {
  throw new Error('Configure spatial encoding in the chart before querying');
}
buildSpatialQuery(formData);

if (!formData.spatial) {
  throw new Error('Spatial configuration missing in form data');
}
buildSpatialQuery(formData);

const hasSpatialConfig = (fd: SpatialFormData): boolean => Boolean(fd.spatial?.type);

try { buildSpatialQuery(formData); } catch (e) { if (e.message.includes('Spatial configuration is required')) showConfigToast(e.message); else throw e; }

When it happens

Trigger: Calling buildSpatialQuery with form data whose spatial field is undefined — a layer chart saved before the spatial control was set, or a query context assembled programmatically without the key.

Common situations: Half-configured deck.gl charts on dashboards; imported dashboards with stripped spatial params; code paths that conditionally attach spatial and skip it for edge-case form states.

Related errors

• Start and end spatial configurations are required for Arc ch
• Spatial configuration is required for Scatter charts
• 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/73ab60529b73f45c. Report an issue: GitHub.