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.

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)

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.