remotion-dev/remotion · error · Error

Invalid runtime preference

Error message

Invalid runtime preference ${option}. Must be one of ${LambdaClientInternals.runtimePreferenceOptions.join(', ')}

What it means

Thrown by validateRuntimePreference(), invoked from deployFunction(), when the runtimePreference value is truthy but not one of the allowed options: 'default', 'apple-emojis', 'cjk'. The preference selects which Lambda layer set is used (e.g. Apple vs Google emoji rendering vs CJK fonts).

Solutions

1. Use one of the exact allowed values: 'default', 'apple-emojis', or 'cjk' (case-sensitive).
2. Omit runtimePreference entirely to accept the default behaviour.
3. Import the RuntimePreference type so TypeScript rejects invalid literals at compile time.

Example fix

// before
deployFunction({region, runtimePreference: 'apple-emoji'})
// after
deployFunction({region, runtimePreference: 'apple-emojis'})

import {runtimePreferenceOptions} from '@remotion/lambda-client'
const pref = process.env.RUNTIME_PREFERENCE
if (pref && !runtimePreferenceOptions.includes(pref)) {
  throw new Error(`runtimePreference must be one of ${runtimePreferenceOptions.join(', ')}`)
}

import {runtimePreferenceOptions, type RuntimePreference} from '@remotion/lambda-client'
const isRuntimePreference = (v: unknown): v is RuntimePreference =>
  typeof v === 'string' && (runtimePreferenceOptions as readonly string[]).includes(v)

When it happens

Trigger: Passing deployFunction({runtimePreference: 'apple-emoji'}), 'Apple', 'system', or any string/number not equal to one of the three allowed values.

Common situations: Misspelling 'apple-emojis' (singular, capitalised, hyphenated differently); copy-pasting an outdated option name from old docs; passing a boolean or numeric code instead of the string literal.

Related errors

• A custom role ARN must either be "undefined" or a string…
• CloudWatch retention period must be an integer, but is NaN
• CloudWatch retention period should be a number, got
• 'expiresIn' should be a number, but is
• maxRetries must be a number, but is

AI-assisted analysis of remotion-dev/remotion@10db9de073 (2026-08-12). Data as JSON: /api/errors/5f329994d74ebbd0. Report an issue: GitHub.

Appendix: source

Thrown at packages/lambda/src/shared/get-layers.ts:16

import type {AwsRegion, RuntimePreference} from '@remotion/lambda-client';
import {LambdaClientInternals} from '@remotion/lambda-client';
import type {AwsLayer, HostedLayerRegion} from './hosted-layers';
import {hostedLayers} from './hosted-layers';

export const validateRuntimePreference = (option: unknown) => {
	if (!option) {
		return;
	}

	if (
		!LambdaClientInternals.runtimePreferenceOptions.includes(
			option as RuntimePreference,
		)
	) {
		throw new Error(
			`Invalid runtime preference ${option}. Must be one of ${LambdaClientInternals.runtimePreferenceOptions.join(
				', ',
			)}`,
		);
	}
};

export const getLayers = ({
	option,
	region,
}: {
	option: RuntimePreference;
	region: AwsRegion;
}): AwsLayer[] => {
	if (!(region in hostedLayers)) {
		throw new Error(`Remotion-hosted Layers are not available in ${region}.`);
	}

View on GitHub (pinned to 10db9de073)