{"record":{"id":"e333e163a52ea922","repo":"remotion-dev/remotion","slug":"backgroundcolor-must-be-a-string","errorCode":null,"errorMessage":"\"backgroundColor\" must be a string","messagePattern":"\"backgroundColor\" must be a string","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/brand/src/effects/metallic-swirl-effect.ts","lineNumber":347,"sourceCode":"\tassertOptionalFiniteNumber(params.zoom, 'zoom');\n\tassertOptionalFiniteNumber(params.iterations, 'iterations');\n\tassertOptionalFiniteNumber(params.sampleGap, 'sampleGap');\n\tassertOptionalFiniteNumber(params.tangentForce, 'tangentForce');\n\tassertOptionalFiniteNumber(params.gradientForce, 'gradientForce');\n\tassertOptionalFiniteNumber(params.colorPhaseR, 'colorPhaseR');\n\tassertOptionalFiniteNumber(params.colorPhaseG, 'colorPhaseG');\n\tassertOptionalFiniteNumber(params.colorPhaseB, 'colorPhaseB');\n\tassertOptionalFiniteNumber(params.colorRange, 'colorRange');\n\tassertOptionalFiniteNumber(params.colorBias, 'colorBias');\n\tassertOptionalFiniteNumber(params.brightness, 'brightness');\n\tassertOptionalFiniteNumber(params.opacity, 'opacity');\n\tassertOptionalEnum(params.mode, 'mode', MODES);\n\n\tif (\n\t\tparams.backgroundColor !== undefined &&\n\t\ttypeof params.backgroundColor !== 'string'\n\t) {\n\t\tthrow new TypeError('\"backgroundColor\" must be a string');\n\t}\n\n\tif (params.colorA !== undefined && typeof params.colorA !== 'string') {\n\t\tthrow new TypeError('\"colorA\" must be a string');\n\t}\n\n\tif (params.colorB !== undefined && typeof params.colorB !== 'string') {\n\t\tthrow new TypeError('\"colorB\" must be a string');\n\t}\n\n\tconst resolved = resolve(params);\n\tvalidateRange(resolved.speed, 'speed', 0, 10);\n\tvalidateRange(resolved.zoom, 'zoom', 0.01, 50);\n\tvalidateRange(resolved.iterations, 'iterations', 1, 12);\n\tvalidateRange(resolved.sampleGap, 'sampleGap', 0.0001, 1);\n\tvalidateRange(resolved.colorRange, 'colorRange', 0, 2);\n\tvalidateRange(resolved.colorBias, 'colorBias', 0, 2);\n\tvalidateRange(resolved.brightness, 'brightness', 0, 5);","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/brand/src/effects/metallic-swirl-effect.ts#L329-L365","documentation":"`validateMetallicSwirlParams` checks `backgroundColor` separately from the generic color parser: if it is present (`!== undefined`) it must be a `string`, otherwise this throws. Note this runs before `parseHexColor`, so a non-string fails here first. A string that is not valid hex instead fails at error 30.","triggerScenarios":"`metallicSwirl({backgroundColor: 0})`, `metallicSwirl({backgroundColor: null})`, `metallicSwirl({backgroundColor: ['#000']})`, `metallicSwirl({backgroundColor: true})`.","commonSituations":"Passing a numeric color code (0x000000) from a different system; null used to mean 'unset'; array from a multi-value form field; boolean toggles.","solutions":["Pass a hex string: `metallicSwirl({backgroundColor: '#000000'})`.","Omit the key entirely to use the default (`#000000`).","Convert numeric codes to `#RRGGBB` at your boundary.","Use `undefined`, not `null`, for 'unset'."],"exampleFix":"// before\nmetallicSwirl({backgroundColor: 0x000000});\n\n// after\nmetallicSwirl({backgroundColor: '#000000'});","handlingStrategy":"type-guard","validationCode":"// Ensure backgroundColor is a string (or omit it).\nconst optionalString = (v: unknown): string | undefined => {\n  if (v === undefined || v === null) return undefined;\n  if (typeof v !== 'string') {\n    throw new Error('backgroundColor must be a string');\n  }\n  return v;\n};\nmetallicSwirl({backgroundColor: optionalString(raw.backgroundColor)});","typeGuard":"const isOptionalString = (v: unknown): v is string =>\n  typeof v === 'string';","tryCatchPattern":null,"preventionTips":["Pass hex strings for color params; never numeric codes or arrays.","Omit the key to use the default backgroundColor instead of passing null.","Type params as `MetallicSwirlParams` so non-strings surface at compile time.","Convert numeric color codes to `#RRGGBB` at your boundary."],"tags":["brand","metallic-swirl","validation","color","params"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}