remotion-dev/remotion · error · Error

customLayerArns cannot be combined with a non-default runtim

Error message

customLayerArns cannot be combined with a non-default runtimePreference.

What it means

validateCustomLayerArns throws when customLayerArns is combined with a runtimePreference other than 'default'. Runtime preferences like 'system-runtime' select a specific Remotion-hosted layer set, which is mutually exclusive with bringing your own layers; the deploy options cannot both take effect.

Source

Thrown at packages/lambda/src/shared/validate-custom-layer-arns.ts:37

	runtimePreference: RuntimePreference;
}) => {
	const {partition} = LambdaClientInternals.getAwsRegionMetadata(region);
	if (customLayerArns === null) {
		if (partition === 'aws-cn') {
			throw new Error(
				'customLayerArns must be specified when deploying to AWS China regions because Remotion-hosted Layers are not available in the aws-cn partition.',
			);
		}

		return;
	}

	if (!Array.isArray(customLayerArns) || customLayerArns.length === 0) {
		throw new TypeError('customLayerArns must contain at least one Layer ARN.');
	}

	if (runtimePreference !== 'default') {
		throw new Error(
			'customLayerArns cannot be combined with a non-default runtimePreference.',
		);
	}

	if (customLayerArns.length + (enableLambdaInsights ? 1 : 0) > 5) {
		throw new Error(
			'Lambda functions support at most 5 Layers, including the Lambda Insights Layer.',
		);
	}

	const seen = new Set<string>();
	for (const layerArn of customLayerArns) {
		if (typeof layerArn !== 'string' || layerArn.length === 0) {
			throw new TypeError(
				'Each customLayerArns entry must be a non-empty string.',
			);
		}

View on GitHub (pinned to 10db9de073)

Solutions

1. Set `runtimePreference: 'default'` when supplying customLayerArns.
2. Or drop customLayerArns and keep the non-default runtimePreference to use Remotion-hosted layers.

Example fix

// before
await deployFunction({
  region: 'us-east-1',
  runtimePreference: 'system-runtime',
  customLayerArns: ['arn:aws:lambda:us-east-1:123456789012:layer:my-chromium:1'],
});

// after
await deployFunction({
  region: 'us-east-1',
  runtimePreference: 'default',
  customLayerArns: ['arn:aws:lambda:us-east-1:123456789012:layer:my-chromium:1'],
});

if (customLayerArns && runtimePreference !== 'default') {
  throw new Error('customLayerArns and non-default runtimePreference are mutually exclusive');
}

When it happens

Trigger: Calling deployFunction with `customLayerArns: [...]` and `runtimePreference: 'system-runtime'` (or any non-default value).

Common situations: Copying a China-region style config (custom layers) into a script that also set a runtimePreference from an earlier experiment; upgrading @remotion/lambda and keeping stale runtimePreference settings in deploy config.

Related errors

• customLayerArns must contain at least one Layer ARN.
• customLayerArns must be specified when deploying to AWS Chin
• Lambda functions support at most 5 Layers, including the Lam
• Each customLayerArns entry must be a non-empty string.
• Invalid Lambda Layer version ARN: ${layerArn}. Expected arn:

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