{"record":{"id":"44f7cb10546d9bc6","repo":"heygen-com/hyperframes","slug":"use-either-apply-with-grading-or-clear-not","errorCode":null,"errorMessage":"Use either --apply with --grading or --clear, not both","messagePattern":"Use either --apply with --grading or --clear, not both","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":514,"sourceCode":"  if (isRemoteOrInlineUrl(sourceUrl)) {\n    throw new Error(\n      \"Media analysis requires a local project asset; freeze remote media with media-use first\",\n    );\n  }\n  const cleanSource = cleanAssetUrl(sourceUrl);\n  if (!cleanSource) throw new Error(\"Selected media has no analyzable local src\");\n  const projectRelative = cleanSource.startsWith(\"/\")\n    ? cleanSource\n    : rewriteAssetPath(compositionFile, cleanSource, (path) => existsSync(join(projectDir, path)));\n  const asset = resolveExistingLocalAsset(projectDir, projectRelative);\n  if (!asset) throw new Error(`Media file not found: ${source}`);\n  return asset.resolved;\n}\n\nfunction parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {\n  if (clear) {\n    if (raw !== undefined || apply) {\n      throw new Error(\"Use either --apply with --grading or --clear, not both\");\n    }\n    return undefined;\n  }\n  if (!apply) {\n    if (raw !== undefined) throw new Error(\"--grading requires --apply\");\n    throw new Error(\"Use --apply with --grading <json> or --clear\");\n  }\n  if (raw === undefined) throw new Error(\"--apply requires --grading <json>\");\n  try {\n    return JSON.parse(raw);\n  } catch (error) {\n    throw new Error(`Could not parse --grading JSON: ${normalizeErrorMessage(error)}`);\n  }\n}\n\nfunction mutationVerb(action: \"apply\" | \"clear\", changed: boolean, dryRun: boolean): string {\n  if (dryRun) return `Would ${action}`;\n  if (!changed) return action === \"apply\" ? \"Already applied\" : \"Already clear\";","sourceCodeStart":496,"sourceCodeEnd":532,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L496-L532","documentation":"Thrown by parseGrading when --clear is set simultaneously with --grading or --apply. The command supports exactly two mutation modes: apply a grading patch (--apply --grading <json>) or remove grading (--clear). Combining them is ambiguous and rejected up front.","triggerScenarios":"Invoking `hyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}' --apply --clear` or `... --grading '{...}' --clear`. Also fires when --clear is combined with --apply even without --grading.","commonSituations":"Agent loops that accumulate flags across iterations. Shell scripts that conditionally append flags without resetting. Copy-pasting a command and appending --clear without removing the apply flags.","solutions":["To apply: use `--grading '<json>' --apply` without --clear","To remove: use `--clear` alone without --grading or --apply","Audit your command string for stale flags before running"],"exampleFix":"// before\nhyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}' --apply --clear\n// after — pick one mode\nhyperframes media-treatment --selector '#hero' --grading '{\"preset\":\"warm\"}' --apply","handlingStrategy":"validation","validationCode":"function validateMutationFlags(opts: { grading?: string; apply?: boolean; clear?: boolean }): void {\n  if (opts.clear && (opts.grading !== undefined || opts.apply)) {\n    throw new Error('Conflicting flags: --clear cannot combine with --grading or --apply');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build mutation commands from a single-mode template, not by accumulating flags","In agent loops, reset the flag set per invocation rather than reusing a base string"],"tags":["media-treatment","cli","argument-conflict","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}