apache/superset · error

A valid color scheme is required

Error message

A valid color scheme is required

What it means

The dashboard Properties modal validates the chosen color scheme against the categorical color scheme registry before saving; an unknown scheme triggers a danger toast and a thrown Error. This happens when json_metadata.color_scheme references a scheme that is not registered in this build (custom schemes must be registered in both backend CATEGORIES and the frontend registry).

Source

Thrown at superset-frontend/src/dashboard/components/PropertiesModal/index.tsx:288

        setColorScheme(originalDashboardMetadata.current.color_scheme ?? ''),
      );
    }
    onHide();
  };

  const onColorSchemeChange = (
    colorScheme = '',
    { updateMetadata = true } = {},
  ) => {
    // check that color_scheme is valid
    const colorChoices = categoricalSchemeRegistry.keys();
    const jsonMetadataObj = getJsonMetadata();

    // only fire if the color_scheme is present and invalid
    if (colorScheme && !colorChoices.includes(colorScheme)) {
      addDangerToast(t('A valid color scheme is required'));
      onHide();
      throw new Error('A valid color scheme is required');
    }

    jsonMetadataObj.color_scheme = colorScheme;
    jsonMetadataObj.label_colors = jsonMetadataObj.label_colors || {};

    setCurrentColorScheme(colorScheme);
    dispatch(setColorScheme(colorScheme));

    // update metadata to match selection
    if (updateMetadata) {
      setJsonMetadata(jsonStringify(jsonMetadataObj));
    }
  };

  const onFinish = () => {
    const {
      title,
      description = '',

View on GitHub (pinned to f4587218dd)

Solutions

1. Pick a scheme from the dropdown's current list (e.g. 'd3Category10', 'supersetColors') and save.
2. Register the custom scheme on the frontend (addColorScheme / superset-ui core register) so it appears in categoricalSchemeRegistry.
3. Remove the stale color_scheme key from the dashboard's json_metadata via the API, then re-select.
4. Keep custom scheme names identical across environments when exporting/importing dashboards.

Example fix

// before
jsonMetadataObj.color_scheme = 'myCustomScheme'; // not registered

// after
import { categoricalSchemeRegistry } from '@superset-ui/core';
const scheme = categoricalSchemeRegistry.defaultKey(); // or a known key
jsonMetadataObj.color_scheme = scheme;

import { categoricalSchemeRegistry } from '@superset-ui/core';

const isValidScheme = (name: string) =>
  categoricalSchemeRegistry.keys().includes(name);

if (colorScheme && !isValidScheme(colorScheme)) {
  colorScheme = categoricalSchemeRegistry.defaultKey();
}

function isRegisteredColorScheme(name: string): boolean {
  return categoricalSchemeRegistry.keys().includes(name);
}

try {
  onColorSchemeChange(colorScheme);
} catch (e) {
  if (e instanceof Error && e.message.includes('color scheme')) {
    // toast already shown by modal; re-select a valid scheme
    return;
  }
  throw e;
}

When it happens

Trigger: Saving dashboard properties with a color scheme value not present in categoricalSchemeRegistry.keys(); importing a dashboard whose metadata names a scheme this deployment does not bundle; a custom scheme plugin not loaded on the frontend but known to the backend.

Common situations: Dashboard exports moved between environments where a custom color scheme exists only in one; the scheme was renamed/removed in an upgrade; custom THEME config added schemes server-side only.

Related errors

• No dashboard found for uuid ${sourceUuid}
• Received unexpected response status (${response.status}) whi
• Dashboard %(dashboard_id)s not found
• Changing one or more of these dashboards is forbidden
• Dashboard parameters are invalid.

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