remotion-dev/remotion · error · Error

Invalid runtime preference ${option}. Must be one of ${Lambd

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).

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} 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[] => {
	const layers = hostedLayers[region];
	return layers.filter((layer) => {
		if (layer.layerArn.includes('emoji-apple')) {
			return option === 'apple-emojis';

View on GitHub (pinned to 78fe4bb3fd)

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

• maxRetries must be a number, but is ${JSON.stringify(maxRetr
• "serveURL" parameter must be a string, but is ${JSON.stringi
• "serviceName" parameter must be a string, but is ${JSON.stri
• The 'siteName' argument must be a string if provided, but is
• The `bundleDir` must be a string, but received ${JSON.string

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