{"record":{"id":"f33708be0d561481","repo":"apache/superset","slug":"a-valid-color-scheme-is-required","errorCode":null,"errorMessage":"A valid color scheme is required","messagePattern":"A valid color scheme is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"superset-frontend/src/dashboard/components/PropertiesModal/index.tsx","lineNumber":288,"sourceCode":"        setColorScheme(originalDashboardMetadata.current.color_scheme ?? ''),\n      );\n    }\n    onHide();\n  };\n\n  const onColorSchemeChange = (\n    colorScheme = '',\n    { updateMetadata = true } = {},\n  ) => {\n    // check that color_scheme is valid\n    const colorChoices = categoricalSchemeRegistry.keys();\n    const jsonMetadataObj = getJsonMetadata();\n\n    // only fire if the color_scheme is present and invalid\n    if (colorScheme && !colorChoices.includes(colorScheme)) {\n      addDangerToast(t('A valid color scheme is required'));\n      onHide();\n      throw new Error('A valid color scheme is required');\n    }\n\n    jsonMetadataObj.color_scheme = colorScheme;\n    jsonMetadataObj.label_colors = jsonMetadataObj.label_colors || {};\n\n    setCurrentColorScheme(colorScheme);\n    dispatch(setColorScheme(colorScheme));\n\n    // update metadata to match selection\n    if (updateMetadata) {\n      setJsonMetadata(jsonStringify(jsonMetadataObj));\n    }\n  };\n\n  const onFinish = () => {\n    const {\n      title,\n      description = '',","sourceCodeStart":270,"sourceCodeEnd":306,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset-frontend/src/dashboard/components/PropertiesModal/index.tsx#L270-L306","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pick a scheme from the dropdown's current list (e.g. 'd3Category10', 'supersetColors') and save.","Register the custom scheme on the frontend (addColorScheme / superset-ui core register) so it appears in categoricalSchemeRegistry.","Remove the stale color_scheme key from the dashboard's json_metadata via the API, then re-select.","Keep custom scheme names identical across environments when exporting/importing dashboards."],"exampleFix":"// before\njsonMetadataObj.color_scheme = 'myCustomScheme'; // not registered\n\n// after\nimport { categoricalSchemeRegistry } from '@superset-ui/core';\nconst scheme = categoricalSchemeRegistry.defaultKey(); // or a known key\njsonMetadataObj.color_scheme = scheme;","handlingStrategy":"validation","validationCode":"import { categoricalSchemeRegistry } from '@superset-ui/core';\n\nconst isValidScheme = (name: string) =>\n  categoricalSchemeRegistry.keys().includes(name);\n\nif (colorScheme && !isValidScheme(colorScheme)) {\n  colorScheme = categoricalSchemeRegistry.defaultKey();\n}","typeGuard":"function isRegisteredColorScheme(name: string): boolean {\n  return categoricalSchemeRegistry.keys().includes(name);\n}","tryCatchPattern":"try {\n  onColorSchemeChange(colorScheme);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('color scheme')) {\n    // toast already shown by modal; re-select a valid scheme\n    return;\n  }\n  throw e;\n}","preventionTips":["Register custom schemes on the frontend registry in every environment that may open the dashboard.","Keep scheme names stable across upgrades; grep dashboard exports before renaming schemes.","After imports, audit json_metadata.color_scheme against the registry."],"tags":["dashboard","color-scheme","metadata","registry"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}