apache/superset · error · Error

Bad spatial key

Error message

Bad spatial key

What it means

Thrown by getSpatialColumns in the deck.gl layers' spatialUtils when the spatial configuration object is null/undefined or lacks a type field. The type discriminator ('latlong' | 'delimited' | 'geohash') selects which column fields to read; without it the function cannot map the config to query columns and rejects the input immediately.

Source

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

  color_scheme?: string;
  color_scheme_type?: string;
  color_breakpoints?: number[];
  default_breakpoint_color?: string;
  tooltip_contents?: unknown[];
  tooltip_template?: string;
  color_picker?: string;
}

export interface SpatialPoint {
  position: [number, number];
  weight: number;
  extraProps?: Record<string, unknown>;
  [key: string]: unknown;
}

export function getSpatialColumns(spatial: SpatialConfiguration): string[] {
  if (!spatial || !spatial.type) {
    throw new Error('Bad spatial key');
  }

  switch (spatial.type) {
    case 'latlong':
      if (!spatial.lonCol || !spatial.latCol) {
        throw new Error(
          'Longitude and latitude columns are required for latlong type',
        );
      }
      return [spatial.lonCol, spatial.latCol];
    case 'delimited':
      if (!spatial.lonlatCol) {
        throw new Error(
          'Longitude/latitude column is required for delimited type',
        );
      }
      return [spatial.lonlatCol];
    case 'geohash':

View on GitHub (pinned to f4587218dd)

Solutions

1. Re-open the chart's spatial control in Explore and pick an encoding (latlong/delimited/geohash) so type is written into the config.
2. If building the config in code, always set type alongside the column fields.
3. Repair stale params via the chart API: PUT /api/v1/chart/{id} with corrected params JSON.

Example fix

// before
getSpatialColumns({ lonCol: 'lon', latCol: 'lat' }); // no type -> throws

// after
getSpatialColumns({ type: 'latlong', lonCol: 'lon', latCol: 'lat' });

if (!spatial?.type) {
  throw new Error('Spatial config missing type');
}
getSpatialColumns(spatial);

const isSpatialConfig = (s: unknown): s is SpatialConfiguration =>
  s != null && typeof s === 'object' && typeof (s as SpatialConfiguration).type === 'string';

try { getSpatialColumns(spatial); } catch (e) { if (e.message === 'Bad spatial key') resetSpatialControl(); else throw e; }

When it happens

Trigger: Calling getSpatialColumns (directly or via buildSpatialQuery / Arc / Scatter buildQuery) with undefined spatial, an empty object, or a config whose 'type' key is missing — e.g. partially deserialized form params or a hand-built spatial object.

Common situations: Saved chart params where spatial serialized as {} after a control reset; imports from older Superset versions with a different spatial schema; code that constructs spatial configs conditionally and skips setting type.

Related errors

• Unknown spatial type: ${spatial.type}
• Start and end spatial configurations are required for Arc ch
• Spatial configuration is required for Scatter charts
• Longitude and latitude columns are required for latlong type
• Longitude/latitude column is required for delimited type

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