mantinedev/mantine · error · Error

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

Error message

[@mantine/core] Failed to parse color. Expected color to be a string, instead got ${typeof color}

What it means

parseThemeColor is the central function Mantine uses to resolve theme colors (e.g. 'blue.5', 'primaryColor'). It only accepts strings; passing a number, null, undefined or an object throws this error. It usually surfaces indirectly through color/style props that ultimately call this parser.

Source

Thrown at packages/@mantine/core/src/core/MantineProvider/color-functions/parse-theme-color/parse-theme-color.ts:27

  colorScheme?: MantineColorScheme;
}

interface ParseThemeColorResult {
  color: string;
  value: string;
  shade: MantineColorShade | undefined;
  variable: CssVariable | undefined;
  isThemeColor: boolean;
  isLight: boolean;
}

export function parseThemeColor({
  color,
  theme,
  colorScheme,
}: ParseThemeColorOptions): ParseThemeColorResult {
  if (typeof color !== 'string') {
    throw new Error(
      `[@mantine/core] Failed to parse color. Expected color to be a string, instead got ${typeof color}`
    );
  }

  if (color === 'bright') {
    return {
      color,
      value: colorScheme === 'dark' ? theme.white : theme.black,
      shade: undefined,
      isThemeColor: false,
      isLight: isLightColor(
        colorScheme === 'dark' ? theme.white : theme.black,
        theme.luminanceThreshold
      ),
      variable: '--mantine-color-bright',
    };
  }

View on GitHub (pinned to 8a284e2c2c)

Solutions

1. Coerce or default the value before passing: color={userColor ?? 'blue' }
2. Fix the data source so color is always a valid string or undefined, and avoid passing undefined explicitly where the prop is typed as string
3. If you need a raw non-theme color, pass it as a string (e.g. '#228be6')

Example fix

// before
<Box color={themeConfig.accent}>...</Box> // themeConfig.accent is undefined

// after
<Box color={themeConfig.accent ?? 'blue'}>...</Box>

const safeColor = (c: unknown) =>
  typeof c === 'string' && c.length > 0 ? c : 'blue';

<Box color={safeColor(config.accent)}>...</Box>;

function isColorString(v: unknown): v is string {
  return typeof v === 'string' && (v === '' || /^[a-zA-Z0-9().#\s-]+$/.test(v));
}

try {
  const parsed = parseThemeColor({ color, theme });
} catch (e) {
  // fall back to a default theme color
}

When it happens

Trigger: Passing a non-string color prop: color={undefined}, color={null}, color={number}, color={{ ... }}; reading a CSS variable or config value that turns out to be undefined; template strings evaluating to non-strings.

Common situations: Dynamic theming where a color comes from an API/config and is missing; conditionally setting color={someVar} where someVar can be undefined; number-based color values from design tokens (e.g. 0xRRGGBB) fed into color props.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• INVALID_PRIMARY_COLOR_ERROR
• INVALID_PRIMARY_SHADE_ERROR

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