remotion-dev/remotion · error

No CLI help metadata exists for --${flag}

Error message

No CLI help metadata exists for --${flag}

What it means

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.

Source

Thrown at packages/cli/src/print-help.ts:47

		description: 'Reduce console output.',
	},
};

const options = (
	flags: readonly string[],
	descriptionOverrides: Record<string, string> = {},
): CommandHelpOption[] => {
	return flags.map((flag) => {
		const cliOnlyOption = cliOnlyOptions[flag];
		if (cliOnlyOption) {
			return cliOnlyOption;
		}

		const rendererOption = rendererOptions.find(
			(candidate) => candidate.cliFlag === flag,
		);
		if (!rendererOption) {
			throw new Error(`No CLI help metadata exists for --${flag}`);
		}

		return makeCommandHelpOption({
			option: rendererOption,
			description: descriptionOverrides[flag],
		});
	});
};

const studioOptions = options([
	'props',
	'config',
	'env-file',
	'log',
	'port',
	'public-dir',
	'binaries-directory',
	'disable-git-source',

View on GitHub (pinned to b2f4e34732)

Solutions

1. Add the missing option entry (with the matching cliFlag and description) to the CLI help metadata table
2. Fix the flag name in the command's options array to match an existing metadata entry
3. Run the CLI's --help output locally to confirm all flags render before committing

Example fix

// before
// command options include 'concurrency' but metadata lacks it
// after
// in the help metadata table:
{cliFlag: 'concurrency', description: 'Set the concurrency of the render'} // registered

// when adding a flag, verify metadata exists:
const meta = rendererOptions.find((o) => o.cliFlag === 'myFlag');
if (!meta) throw new Error('register help metadata for --myFlag first');

try {
	helpOutput = options(...);
} catch (err) {
	if ((err as Error).message.startsWith('No CLI help metadata exists for')) {
		console.error('Developer error: register the flag in the CLI metadata table.');
	} else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• No Cloud Run CLI help metadata exists for --${flag}
• The following packages are not Remotion packages: ${invalidP
• Could not determine version of installed Remotion packages:
• No Remotion packages found in your project. Install Remotion
• No lockfile was found in your project (one of ${StudioServer

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/129d257f7d7011d2. Report an issue: GitHub.