{"record":{"id":"06a46e05ae7bee9d","repo":"heygen-com/hyperframes","slug":"invalid-color-grading-issue-path-issue-messa","errorCode":null,"errorMessage":"Invalid color-grading ${issue.path}: ${issue.message}.${hint}","messagePattern":"Invalid color-grading (.+?): (.+?)\\.(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":354,"sourceCode":"interface ApplyMediaTreatmentResult {\n html: string;\n changed: boolean;\n tag: \"img\" | \"video\";\n value: string | null;\n before: unknown;\n after: unknown;\n}\n\nfunction parseSourceDocument(source: string): Document {\n if (/]/i.test(source)) return parseHTML(source).document;\n return parseHTML(`${source}`).document;\n}\n\nfunction assertKnownGradingShape(value: unknown): void {\n const issue = validateColorGradingContract(value)[0];\n if (issue) {\n const hint = issue.hint ? ` ${issue.hint}` : \"\";\n throw new Error(`Invalid color-grading ${issue.path}: ${issue.message}.${hint}`);\n }\n}\n\nfunction containsColorGradingVariableRef(value: unknown): boolean {\n if (isColorGradingVariableRef(value)) return true;\n if (Array.isArray(value)) return value.some(containsColorGradingVariableRef);\n if (typeof value !== \"object\" || value === null) return false;\n return Object.values(value).some(containsColorGradingVariableRef);\n}\n\nfunction isRecord(value: unknown): value is Record {\n return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction parseStoredGrading(raw: string | null): unknown {\n if (raw === null) return null;\n try {\n return JSON.parse(raw);","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L336-L372","documentation":"Thrown by assertKnownGradingShape() in packages/cli/src/commands/media-treatment.ts:350. It runs validateColorGradingContract (from @hyperframes/parsers/color-grading-contract) on the --grading value and, if any issue is found, throws the FIRST issue's path, message, and optional hint. This is the structural/shape validator invoked before any patch is merged or written.","triggerScenarios":"Passing `--grading ''` whose shape violates the contract: unknown top-level keys, wrong type for a section (e.g. wheels as a string), out-of-range numeric values, malformed curve points, or unknown secondary/palette shape.","commonSituations":"Hand-typed grading JSON with a typo'd section name; placing top-level keys (like 'shadows') directly under grading instead of under 'wheels'; using control names from a different CLI version; numeric values outside the documented bounds.","solutions":["Read the message: it names the path (e.g. 'grading.wheels.shadows') and the violation; fix that exact location.","Inspect the canonical contract: `hyperframes media-treatment --capability grading --json` (and per-control: --capability wheels / curves / hue-curves / secondary).","Validate the JSON parses first (a separate 'Could not parse --grading JSON' error covers parse failures).","After editing, run with --dry-run --json to re-validate before writing."],"exampleFix":"# before -- bad shape (shadows at top level)\nhyperframes media-treatment -s '#hero' \\\n --grading '{\"shadows\":{\"hue\":200}}' --apply\n# after -- shadows belongs under wheels\nhyperframes media-treatment -s '#hero' \\\n --grading '{\"wheels\":{\"shadows\":{\"hue\":200,\"amount\":0.1,\"level\":0}}}' --apply","handlingStrategy":"validation","validationCode":"import { validateColorGradingContract } from '@hyperframes/parsers/color-grading-contract';\n\nfunction isValidGrading(value: unknown): boolean {\n return validateColorGradingContract(value).length === 0;\n}\n\nconst parsed = JSON.parse(gradingJson);\nif (!isValidGrading(parsed)) {\n throw new Error('Grading JSON violates the contract — see --capability grading');\n}","typeGuard":"import { validateColorGradingContract } from '@hyperframes/parsers/color-grading-contract';\n\nfunction isValidGradingShape(value: unknown): boolean {\n return validateColorGradingContract(value).length === 0;\n}","tryCatchPattern":"try {\n applyMediaTreatmentToHtml(source, { selector, grading: parsed, apply: true });\n} catch (error) {\n if (/Invalid color-grading/.test(String(error))) {\n // re-fetch the contract for the offending path and surface it to the user\n throw new Error(`Grading rejected: ${error}`);\n }\n throw error;\n}","preventionTips":["Validate grading JSON with validateColorGradingContract before passing it to --grading.","Always run with --dry-run --json first to catch contract issues without writing.","Pull control shapes from `--capability ` rather than guessing."],"tags":["cli","validation","color-grading"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}