apache/superset · warning

Theme mode changes are not allowed when only one theme is av

Error message

Theme mode changes are not allowed when only one theme is available

What it means

ThemeController.validateModeUpdatePermission throws when canSetMode() is false, which happens when no dark theme is available — with only a single (light) theme there is nothing to switch modes between, so 'dark'/'system' mode requests are rejected. The message names exactly this condition.

Source

Thrown at superset-frontend/src/theme/ThemeController.ts:871

    }
  }

  /**
   * Validates permission to update theme.
   */
  private validateThemeUpdatePermission(): void {
    if (!this.canSetTheme())
      throw new Error('User does not have permission to update the theme');
  }

  /**
   * Validates permission to update mode.
   * @throws {Error} If the user does not have permission to update the theme mode
   */
  private validateModeUpdatePermission(): void {
    // Check if user can set a new theme mode (dark theme must exist)
    if (!this.canSetMode())
      throw new Error(
        'Theme mode changes are not allowed when only one theme is available',
      );
  }

  /**
   * Applies the current theme configuration to the global theme.
   * This method sets the theme on the globalTheme and applies it to the Theme.
   * It also handles any errors that may occur during the application of the theme.
   * @param theme - The theme configuration to apply (may already include base theme tokens)
   */
  private applyTheme(theme: AnyThemeConfig): void {
    try {
      const normalizedConfig = normalizeThemeConfig(theme);

      // Simply apply the theme - it should already be properly merged if needed
      // The merging with base theme happens in getThemeForMode() and other methods
      // that prepare themes before passing them to applyTheme()
      this.globalTheme.setConfig(normalizedConfig);

View on GitHub (pinned to f4587218dd)

Solutions

1. Provide a dark theme variant to the ThemeController so both modes exist.
2. Only expose a mode switcher in the UI when themeController.canSetMode() is true.
3. In embedded hosts, check canSetMode() before posting setThemeMode over the Switchboard.
4. If dark mode was intentionally disabled, stop sending mode-change requests.

Example fix

// before
themeController.setMode('dark');

// after
if (!themeController.canSetMode()) {
  logging.warn('Mode changes disabled: no dark theme available');
  return;
}
themeController.setMode('dark');

if (!themeController.canSetMode()) {
  // no dark theme available; keep mode controls hidden
  return;
}
themeController.setMode(mode);

type ThemeMode = 'default' | 'dark' | 'system';

function isThemeMode(v: unknown): v is ThemeMode {
  return v === 'default' || v === 'dark' || v === 'system';
}

try {
  themeController.setMode(mode);
} catch (e) {
  if (e instanceof Error && e.message.includes('only one theme')) {
    logging.warn('Dark theme missing; mode change ignored');
    return;
  }
  throw e;
}

When it happens

Trigger: Calling setMode('dark') or setMode('system') when the ThemeController was initialized without a darkTheme; embedded host sends setThemeMode while the deployment only registered a light theme.

Common situations: Custom theme packages that only ship a light variant; feature flag/config disabling dark theme; upgrading Superset where the dark theme token file moved and the custom theme no longer resolves it.

Related errors

• User does not have permission to update the theme
• Failed to apply theme config: ${error.message}
• Chart ${id} is missing form_data
• Changing this Dashboard is forbidden
• Theme not found.

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