GitbookIO/gitbook · error · Error

Invalid hex color provided: ${originalHex}

Error message

Invalid hex color provided: ${originalHex}

What it means

Thrown by hexToRgbArray in @gitbook/colors when a hex color string cannot be parsed into valid RGB channels (e.g. wrong length, non-hex characters, or a channel value outside 0-255). The library strictly expects 3- or 6-digit hex color strings (with or without '#') because all color transformations (shades, mixing, foreground contrast) are computed in RGB space. Any malformed input like 'rgb(0,0,0)', '#GGG', or an undefined variable resolves to this error.

Source

Thrown at packages/colors/src/transformations.ts:326

 * Convert a hex color to an RGB color set.
 */
export function hexToRgbArray(hex: string): RGBColor {
    const originalHex = hex;

    let value = hex.replace('#', '');
    if (hex.length === 3) value = value + value;

    const r = value.substring(0, 2);
    const g = value.substring(2, 4);
    const b = value.substring(4, 6);

    const rgb = [r, g, b].map((channel) => {
        try {
            const channelInt = Number.parseInt(channel, 16);
            if (channelInt < 0 || channelInt > 255) throw new Error();
            return channelInt;
        } catch {
            throw new Error(`Invalid hex color provided: ${originalHex}`);
        }
    });

    return rgb as RGBColor;
}

/**
 * Convert a RGB color set to a hex color.
 */
export function rgbArrayToHex(rgb: RGBColor): string {
    return `#${rgb
        .map((channel) => {
            const component = channel.toString(16);
            if (component.length === 1) return `0${component}`;
            return component;
        })
        .join('')}`;
}

View on GitHub (pinned to db67585ee2)

Solutions

1. Verify the input is a 3- or 6-digit hex string like '#1a2b3c' or '1a2b3c' and strip whitespace before calling the API
2. Normalize other CSS formats (rgb(), named colors) to hex before passing them, e.g. with a small converter or a design-token pipeline
3. If the value comes from user/CMS config, validate it against /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i and fall back to a default color
4. Check for undefined/null caused by a missing property name or typo in the color object being indexed

Example fix

// before
const shades = shadesOfColor(theme.accent /* 'rgb(59, 130, 246)' */);

// after
const shades = shadesOfColor('#3b82f6');

const HEX_RE = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
const safeColor = HEX_RE.test(color) ? color : '#000000';
const shades = shadesOfColor(safeColor);

function isHexColor(value: unknown): value is string {
    return typeof value === 'string' && /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim());
}

try {
    const shades = shadesOfColor(color);
} catch (error) {
    if (error instanceof Error && error.message.startsWith('Invalid hex color provided:')) {
        return shadesOfColor('#000000'); // fallback
    }
    throw error;
}

When it happens

Trigger: Calling shadesOfColor, mixColor, foregroundColor, or baseColor with a non-hex string; passing a CSS color name ('red'), an rgb()/hsl() string, a 4- or 8-digit hex with alpha, or an undefined/null value that stringifies to 'undefined'.

Common situations: Reading theme colors from user config or CMS data where the value is sometimes a CSS color name or empty; passing Tailwind class tokens instead of raw hex; trailing whitespace or newlines in the hex string; values from an environment variable that was never set.

Related errors

• Expected schema of object to be provided: ${schema.type}
• Unsupported schema type: ${schema.type}
• invalid

AI-assisted analysis of GitbookIO/gitbook@db67585ee2 (2026-08-28). Data as JSON: /api/errors/c5c7f3951cbe16c3. Report an issue: GitHub.