mantinedev/mantine · error · Error

INVALID_PRIMARY_COLOR_ERROR

Error message

INVALID_PRIMARY_COLOR_ERROR

What it means

When a theme is created (createTheme) or merged in MantineProvider, Mantine validates that theme.primaryColor exists as a key in theme.colors. If the specified primary color name is not in the colors map, this error is thrown at provider mount time.

Solutions

1. Add the matching color to the theme: createTheme({ colors: { brand: [...10 shades] }, primaryColor: 'brand' })
2. Or set primaryColor to an existing default color name like 'blue'
3. Verify the colors object passed to MantineProvider's theme prop actually contains the primaryColor key

Example fix

// before
const theme = createTheme({ primaryColor: 'brand' }); // colors.brand missing

// after
const theme = createTheme({
  primaryColor: 'brand',
  colors: {
    brand: ['#f0f4ff', '#dce6fb', '#bac8f7', '#94aaf1', '#7190ec', '#5878e9', '#4466e7', '#3455d1', '#2c49ba', '#233c9e'],
  },
});

function validateTheme(colors: Record<string, unknown>, primaryColor: string) {
  if (!(primaryColor in colors)) {
    throw new Error(`primaryColor "${primaryColor}" missing from colors`);
  }
}

function isValidThemeConfig(
  t: MantineThemeOverride
): boolean {
  return !t.primaryColor || (t.primaryColor ?? 'blue') in { ...defaultColors, ...(t.colors ?? {}) };
}

When it happens

Trigger: createTheme({ primaryColor: 'brand' }) without defining colors.brand; overriding colors (e.g. colors: { blue: [...] }) removing the default used by primaryColor; typo in primaryColor name; setting primaryColor but forgetting to pass the custom colors object to MantineProvider theme.

Common situations: Brand theming where primaryColor: 'brand' is set but the colors override is applied in a different theme instance; partial theme overrides that remove default colors; renaming color keys during refactor; copy-pasting theme config between projects with different palettes.

Related errors

• INVALID_PRIMARY_SHADE_ERROR
• [@mantine/core] Failed to parse color. Expected color to be…

AI-assisted analysis of mantinedev/mantine@8a284e2c2c (2026-08-28). Data as JSON: /api/errors/930ddf13f8721356. Report an issue: GitHub.

Appendix: source

Thrown at packages/@mantine/core/src/core/MantineProvider/merge-mantine-theme/merge-mantine-theme.ts:20

import type { MantineTheme, MantineThemeOverride } from '../theme.types';

export const INVALID_PRIMARY_COLOR_ERROR =
  '[@mantine/core] MantineProvider: Invalid theme.primaryColor, it accepts only key of theme.colors, learn more – https://mantine.dev/theming/colors/#primary-color';

export const INVALID_PRIMARY_SHADE_ERROR =
  '[@mantine/core] MantineProvider: Invalid theme.primaryShade, it accepts only 0-9 integers or an object { light: 0-9, dark: 0-9 }';

function isValidPrimaryShade(shade: number) {
  if (shade < 0 || shade > 9) {
    return false;
  }

  return parseInt(shade.toString(), 10) === shade;
}

export function validateMantineTheme(theme: MantineTheme): asserts theme is MantineTheme {
  if (!(theme.primaryColor in theme.colors)) {
    throw new Error(INVALID_PRIMARY_COLOR_ERROR);
  }

  if (typeof theme.primaryShade === 'object') {
    if (
      !isValidPrimaryShade(theme.primaryShade.dark) ||
      !isValidPrimaryShade(theme.primaryShade.light)
    ) {
      throw new Error(INVALID_PRIMARY_SHADE_ERROR);
    }
  }

  if (typeof theme.primaryShade === 'number' && !isValidPrimaryShade(theme.primaryShade)) {
    throw new Error(INVALID_PRIMARY_SHADE_ERROR);
  }
}

export function mergeMantineTheme(
  currentTheme: MantineTheme,

View on GitHub (pinned to 8a284e2c2c)