remotion-dev/remotion · error

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

Error message

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

What it means

The Lambda CLI help generator maps renderer options (from @remotion/renderer metadata) onto Lambda-specific help output. When a flag listed as needing a help entry has no matching renderer option with that cliFlag, this invariant error is thrown. It indicates the Lambda package and renderer package metadata are out of sync — a library bug, not a user error.

Source

Thrown at packages/lambda/src/cli/help.ts:168

	},
	quiet: {flag: '--quiet, -q', description: 'Reduce console output.'},
};

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

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

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

const commandHelp = [
	{
		path: [],
		args: ' <command>',
		description: 'Control Remotion Lambda.',
		documentation: 'https://www.remotion.dev/docs/lambda/cli',
		options: [],
	},
	{

View on GitHub (pinned to b2f4e34732)

Solutions

1. Ensure all @remotion/* packages are on the same version (npx remotion upgrade, or check node_modules for mismatched versions).
2. Delete node_modules and lockfile, reinstall, and rebuild so Lambda and renderer metadata match.
3. Check the flag name for typos; only flags defined in @remotion/renderer's option metadata are supported.
4. If triggered by custom code, register the flag in rendererOptions or remove it from descriptionOverrides. This is otherwise a Remotion bug — file an issue.

Example fix

// before (mismatched versions)
"@remotion/lambda": "4.0.220",
"@remotion/renderer": "4.0.236"
// after
"@remotion/lambda": "4.0.236",
"@remotion/renderer": "4.0.236"

const flagToCheck = 'concurrency';
if (!rendererOptions.some((o) => o.cliFlag === flagToCheck)) {
  console.warn(`Flag --${flagToCheck} has no Lambda help metadata`);
}

function hasHelpMetadata(flag: string): boolean {
  return rendererOptions.some((o) => o.cliFlag === flag);
}

When it happens

Trigger: Running a Lambda CLI command's help (or options resolution) where the internal rendererOptions list has been filtered or is missing a candidate whose cliFlag equals the requested flag — e.g. after a Remotion version mismatch where CLI code expects a newer flag than the metadata provides.

Common situations: Mixed @remotion/* package versions in node_modules after a partial upgrade, a typo'd or renamed flag passed into an internal descriptionOverrides map, or custom tooling calling CliInternals.options() with an unknown flag.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Image format mismatch: ${outName} was given as the ${outName
• Image format mismatch: ${outName} was given as the ${outName
• Pass --s3-output-provider-endpoint when using S3 output prov
• Pass --force-bucket-name when using S3 output provider flags
• Pass --out-name when using S3 output provider flags.

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