{"record":{"id":"129d257f7d7011d2","repo":"remotion-dev/remotion","slug":"no-cli-help-metadata-exists-for-flag","errorCode":null,"errorMessage":"No CLI help metadata exists for --${flag}","messagePattern":"No CLI help metadata exists for --(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/print-help.ts","lineNumber":47,"sourceCode":"\t\tdescription: 'Reduce console output.',\n\t},\n};\n\nconst options = (\n\tflags: readonly string[],\n\tdescriptionOverrides: Record<string, string> = {},\n): CommandHelpOption[] => {\n\treturn flags.map((flag) => {\n\t\tconst cliOnlyOption = cliOnlyOptions[flag];\n\t\tif (cliOnlyOption) {\n\t\t\treturn cliOnlyOption;\n\t\t}\n\n\t\tconst rendererOption = rendererOptions.find(\n\t\t\t(candidate) => candidate.cliFlag === flag,\n\t\t);\n\t\tif (!rendererOption) {\n\t\t\tthrow new Error(`No CLI help metadata exists for --${flag}`);\n\t\t}\n\n\t\treturn makeCommandHelpOption({\n\t\t\toption: rendererOption,\n\t\t\tdescription: descriptionOverrides[flag],\n\t\t});\n\t});\n};\n\nconst studioOptions = options([\n\t'props',\n\t'config',\n\t'env-file',\n\t'log',\n\t'port',\n\t'public-dir',\n\t'binaries-directory',\n\t'disable-git-source',","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/cli/src/print-help.ts#L29-L65","documentation":"The CLI help printer builds help entries by looking up each flag in the shared rendererOptions metadata table. If a flag listed in a command's option set has no matching metadata entry (cliFlag not found), Remotion throws — this catches a developer adding a CLI flag without registering its help metadata. It is an internal consistency check, not a user-input error.","triggerScenarios":"Adding a new CLI option to a command's options array without adding a corresponding entry with cliFlag to the options metadata (printCliHelp / rendererOptions); renaming a cliFlag in one place but not the other.","commonSituations":"Contributing a new CLI flag to packages/cli and forgetting the help metadata registration; typos in the flag string between the option definition and the metadata table.","solutions":["Add the missing option entry (with the matching cliFlag and description) to the CLI help metadata table","Fix the flag name in the command's options array to match an existing metadata entry","Run the CLI's --help output locally to confirm all flags render before committing"],"exampleFix":"// before\n// command options include 'concurrency' but metadata lacks it\n// after\n// in the help metadata table:\n{cliFlag: 'concurrency', description: 'Set the concurrency of the render'} // registered","handlingStrategy":"try-catch","validationCode":"// when adding a flag, verify metadata exists:\nconst meta = rendererOptions.find((o) => o.cliFlag === 'myFlag');\nif (!meta) throw new Error('register help metadata for --myFlag first');","typeGuard":null,"tryCatchPattern":"try {\n\thelpOutput = options(...);\n} catch (err) {\n\tif ((err as Error).message.startsWith('No CLI help metadata exists for')) {\n\t\tconsole.error('Developer error: register the flag in the CLI metadata table.');\n\t} else throw err;\n}","preventionTips":["Always add help metadata in the same PR as a new CLI flag","Grep for the flag string in both the command definition and the metadata table","Run --help for the command locally before merging"],"tags":["cli","documentation","internal-invariant"],"backgroundTag":"missing-required-config-field","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}