remotion-dev/remotion · error · Error

Lambda functions support at most 5 Layers, including the Lam

Error message

Lambda functions support at most 5 Layers, including the Lambda Insights Layer.

What it means

validateCustomLayerArns enforces the AWS hard limit of five Lambda layers per function. It counts your customLayerArns plus one extra slot if enableLambdaInsights is true, and throws as soon as the total would exceed five, so the deploy fails before hitting the AWS API limit.

Source

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

				'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.',
			);
		}

		const match = layerArn.match(layerVersionArnRegex);
		if (!match) {
			throw new TypeError(
				`Invalid Lambda Layer version ARN: ${layerArn}. Expected arn:<partition>:lambda:<region>:<12-digit-account-id>:layer:<layer-name>:<numeric-version>.`,
			);
		}

View on GitHub (pinned to 10db9de073)

Solutions

Reduce customLayerArns to at most five entries, or four when enableLambdaInsights is true.
Merge several small layers into one ZIP (e.g. fonts + shared libraries) to free slots.
Disable enableLambdaInsights if you do not need the CloudWatch Lambda Insights layer.

Example fix

// before
await deployFunction({
  region: 'us-east-1',
  enableLambdaInsights: true,
  customLayerArns: [arn1, arn2, arn3, arn4, arn5], // 5 + insights = 6
});

// after
await deployFunction({
  region: 'us-east-1',
  enableLambdaInsights: true,
  customLayerArns: [arn1, arn2, arn3, arnMergedFontsAndLibs], // 4 + insights = 5
});

Defensive patterns

Strategy: validation

Validate before calling

const total = customLayerArns.length + (enableLambdaInsights ? 1 : 0);
if (total > 5) {
  throw new Error(`Layer budget exceeded: ${total}/5 — merge layers or disable insights`);
}

Prevention

Model the 5-layer cap (minus one for insights) as a deploy-time invariant in your config builder.
Prefer few consolidated layers over many small ones.

When it happens

Trigger: Calling deployFunction with six or more customLayerArns, or five customLayerArns together with `enableLambdaInsights: true`.

Common situations: Attaching many optional layers (chromium, fonts, ffmpeg, shared libs, monitoring agent) and forgetting the insights layer consumes a slot; consolidating layers after splitting a monolithic layer.

Related errors

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