{"record":{"id":"c5c7f3951cbe16c3","repo":"GitbookIO/gitbook","slug":"invalid-hex-color-provided-originalhex","errorCode":null,"errorMessage":"Invalid hex color provided: ${originalHex}","messagePattern":"Invalid hex color provided: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/colors/src/transformations.ts","lineNumber":326,"sourceCode":" * Convert a hex color to an RGB color set.\n */\nexport function hexToRgbArray(hex: string): RGBColor {\n    const originalHex = hex;\n\n    let value = hex.replace('#', '');\n    if (hex.length === 3) value = value + value;\n\n    const r = value.substring(0, 2);\n    const g = value.substring(2, 4);\n    const b = value.substring(4, 6);\n\n    const rgb = [r, g, b].map((channel) => {\n        try {\n            const channelInt = Number.parseInt(channel, 16);\n            if (channelInt < 0 || channelInt > 255) throw new Error();\n            return channelInt;\n        } catch {\n            throw new Error(`Invalid hex color provided: ${originalHex}`);\n        }\n    });\n\n    return rgb as RGBColor;\n}\n\n/**\n * Convert a RGB color set to a hex color.\n */\nexport function rgbArrayToHex(rgb: RGBColor): string {\n    return `#${rgb\n        .map((channel) => {\n            const component = channel.toString(16);\n            if (component.length === 1) return `0${component}`;\n            return component;\n        })\n        .join('')}`;\n}","sourceCodeStart":308,"sourceCodeEnd":344,"githubUrl":"https://github.com/GitbookIO/gitbook/blob/db67585ee243d063c459a855988f21612cea9c95/packages/colors/src/transformations.ts#L308-L344","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Verify the input is a 3- or 6-digit hex string like '#1a2b3c' or '1a2b3c' and strip whitespace before calling the API","Normalize other CSS formats (rgb(), named colors) to hex before passing them, e.g. with a small converter or a design-token pipeline","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","Check for undefined/null caused by a missing property name or typo in the color object being indexed"],"exampleFix":"// before\nconst shades = shadesOfColor(theme.accent /* 'rgb(59, 130, 246)' */);\n\n// after\nconst shades = shadesOfColor('#3b82f6');","handlingStrategy":"validation","validationCode":"const HEX_RE = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;\nconst safeColor = HEX_RE.test(color) ? color : '#000000';\nconst shades = shadesOfColor(safeColor);","typeGuard":"function isHexColor(value: unknown): value is string {\n    return typeof value === 'string' && /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim());\n}","tryCatchPattern":"try {\n    const shades = shadesOfColor(color);\n} catch (error) {\n    if (error instanceof Error && error.message.startsWith('Invalid hex color provided:')) {\n        return shadesOfColor('#000000'); // fallback\n    }\n    throw error;\n}","preventionTips":["Store design tokens as 6-digit hex only","Validate user-configurable colors against a hex regex at config load time","Normalize rgb()/named colors to hex in a preprocessing step"],"tags":["color","hex","validation","colors"],"backgroundTag":"invalid-color-format","analyzedSha":"db67585ee243d063c459a855988f21612cea9c95","analyzedAt":"2026-08-28T17:49:47.831Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}