apache/superset · error · SystemThemeProtectedError

Cannot modify system themes.

Error message

Cannot modify system themes.

What it means

Raised by UpdateThemeCommand.validate() when the target theme has is_system=True. System themes are protected built-ins; the guard fires before ThemeDAO.update, so system theme configuration is immutable through the normal update command.

Source

Thrown at superset/commands/theme/update.py:54

        self._properties = data.copy()
        self._model: Optional[Theme] = None

    @transaction(on_error=partial(on_error, reraise=Exception))
    def run(self) -> Theme:
        self.validate()
        assert self._model
        theme = ThemeDAO.update(self._model, self._properties)
        return theme

    def validate(self) -> None:
        # Validate theme exists
        self._model = ThemeDAO.find_by_id(self._model_id)
        if not self._model:
            raise ThemeNotFoundError()

        # Check if it's a system theme
        if self._model.is_system:
            raise SystemThemeProtectedError()

View on GitHub (pinned to f4587218dd)

Solutions

1. Duplicate the system theme into a new user-owned theme and edit the copy.
2. If you truly must change a system theme, do it through whatever import/seed mechanism owns system records, not the update API.
3. Filter is_system themes out of editable lists in admin UIs.

Example fix

# before
UpdateThemeCommand(model_id=system_theme.id, properties={"theme": cfg}).run()

# after
clone = ThemeDAO.create({"theme_name": f"{system_theme.theme_name} copy", "theme": cfg, ...})
UpdateThemeCommand(model_id=clone.id, properties={"theme": cfg}).run()

theme = ThemeDAO.find_by_id(model_id)
if theme and theme.is_system:
    raise PermissionError("clone the system theme instead of editing it")

from superset.commands.theme.exceptions import SystemThemeProtectedError
try:
    UpdateThemeCommand(model_id, props).run()
except SystemThemeProtectedError:
    clone_then_update(model_id, props)

When it happens

Trigger: PATCHing a built-in/system theme record (one flagged is_system in the theme table) with modified properties.

Common situations: Attempting to customize a shipped theme instead of duplicating it; admin tooling that iterates all themes and updates them indiscriminately; misunderstanding that system themes must be cloned, not edited.

Related errors

• Theme not found.
• Theme not found.
• Subjects are invalid
• Datasource does not exist
• Tag ID {tag_id} not found

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