mantinedev/mantine · error · Error

INVALID_PRIMARY_SHADE_ERROR

Error message

INVALID_PRIMARY_SHADE_ERROR

What it means

Mantine validates that primaryShade (when an object with dark/light keys) contains integer shade indices 0-9. This error is thrown at theme validation when either primaryShade.dark or primaryShade.light is not an integer in the valid range (e.g. 4.5, a string, or out-of-range).

Source

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

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,
  themeOverride?: MantineThemeOverride
) {
  if (!themeOverride) {
    validateMantineTheme(currentTheme);
    return currentTheme;
  }

  const result = deepMerge(currentTheme, themeOverride);

View on GitHub (pinned to 8a284e2c2c)

Solutions

1. Set integer shades between 0 and 9 for both dark and light
2. Coerce config values: Number(...)/parseInt and validate range before building the theme

Example fix

// before
const theme = createTheme({ primaryShade: { light: 4.5, dark: 8 } });

// after
const theme = createTheme({ primaryShade: { light: 4, dark: 8 } });

const shade = (v: unknown) =>
  Number.isInteger(v) && v >= 0 && v <= 9 ? v : 5;

createTheme({
  primaryShade: { light: shade(cfg.light), dark: shade(cfg.dark) },
});

function isValidShade(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 9;
}

When it happens

Trigger: createTheme({ primaryShade: { light: 4.5, dark: 8 } }); passing a string like '5'; passing a negative number or a value above 9.

Common situations: Reading shade values from CSS variables or config files where they arrive as strings; calculations producing fractional shades; copy-pasted theme snippets with typo'd shade values.

Related errors

• INVALID_PRIMARY_COLOR_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/e840395973f745b3. Report an issue: GitHub.