remotion-dev/remotion · critical · Error

Lambda function ${functionName} failed with an unhandled err

Error message

Lambda function ${functionName} failed with an unhandled error: ${event.InvokeComplete.ErrorDetails} See ${logs} to see the logs of this invocation.

What it means

Thrown by the streaming invocation loop in @remotion/lambda-client when an InvokeComplete event arrives with ErrorCode === 'Unhandled'. 'Unhandled' is AWS's signal that the Lambda runtime could not start the handler at all (e.g. function threw synchronously during init, out-of-memory at startup, module load failure, or the handler crashed before any try/catch in Remotion code ran). The error includes a deep-linked CloudWatch Logs Insights URL filtered to the requestId so you can jump straight to the failing invocation's logs.

Source

Thrown at packages/lambda-client/src/call-lambda-streaming.ts:151

	}

	const events =
		res.EventStream as AsyncIterable<InvokeWithResponseStreamResponseEvent>;

	for await (const event of events) {
		// There are two types of events you can get on a stream.

		// `PayloadChunk`: These contain the actual raw bytes of the chunk
		// It has a single property: `Payload`
		if (event.PayloadChunk && event.PayloadChunk.Payload) {
			onData(event.PayloadChunk.Payload);
		}

		if (event.InvokeComplete) {
			if (event.InvokeComplete.ErrorCode) {
				const logs = `https://${region}.console.aws.amazon.com/cloudwatch/home?region=${region}#logsV2:logs-insights$3FqueryDetail$3D~(end~0~start~-3600~timeType~'RELATIVE~unit~'seconds~editorString~'fields*20*40timestamp*2c*20*40requestId*2c*20*40message*0a*7c*20filter*20*40requestId*20like*20*${res.$metadata.requestId}*22*0a*7c*20sort*20*40timestamp*20asc~source~(~'*2faws*2flambda*2f${functionName}))`;
				if (event.InvokeComplete.ErrorCode === 'Unhandled') {
					throw new Error(
						`Lambda function ${functionName} failed with an unhandled error: ${
							event.InvokeComplete.ErrorDetails as string
						} See ${logs} to see the logs of this invocation.`,
					);
				}

				throw new Error(
					`Lambda function ${functionName} failed with error code ${event.InvokeComplete.ErrorCode}: ${event.InvokeComplete.ErrorDetails}. See ${logs} to see the logs of this invocation.`,
				);
			}
		}

		// Don't put a `break` statement here, as it will cause the socket to not properly exit.
	}

	// @ts-expect-error - We are adding a listener to a global variable
	if (globalThis._dumpUnreleasedBuffers) {
		// @ts-expect-error - We are adding a listener to a global variable

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Open the CloudWatch Logs Insights URL embedded in the error message to read the exact runtime stack.
Redeploy the function to ensure the bundle matches your @remotion/lambda version: npx remotion lambda functions deploy.
Increase the function memory (more memory also raises CPU) if init is OOM.
Confirm the Node runtime the function was deployed with is supported by your Remotion version.
Re-check that the Lambda layer(s) (chromium, fonts) are present and compatible.

Example fix

// before
await renderMediaOnLambda({ functionName: 'remotion-render', memorySizeInMb: 512 }); // OOM at cold start -> Unhandled

// after
// Redeploy with more memory and a fresh bundle
await deployFunction({ memorySizeInMb: 2048, timeoutInSeconds: 300 });
await renderMediaOnLambda({ functionName: 'remotion-render' });

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await renderMediaOnLambda({ ... });
} catch (e) {
  if (String((e as Error).message).includes('failed with an unhandled error')) {
    // extract the CloudWatch URL from the message, open it, diagnose cold-start/init failure
  }
  throw e;
}

Prevention

Keep the deployed function bundle and the client on the same @remotion/lambda version.
Size the function memory for cold-start init (>= 2048 MB for typical renders).
Ensure the chromium layer / runtime matches the deployed Node version.

When it happens

Trigger: The deployed renderer function throws during cold-start init (missing dependency, bad env var, broken import), runs out of memory at startup, has a handler signature mismatch, or hits a runtime fatal (e.g. Node segfault) before Remotion's error handling engages.

Common situations: Deploying a function from a mismatched/older bundle; a dependency missing from the Lambda layer; an incompatible Node runtime version; a broken chromium/headless binary in the layer; insufficient memory for the renderer bootstrap.

Related errors

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