{"record":{"id":"ccee7400bdcdb2d1","repo":"remotion-dev/remotion","slug":"lambda-function-functionname-failed-with-an-unh","errorCode":null,"errorMessage":"Lambda function ${functionName} failed with an unhandled error: ${event.InvokeComplete.ErrorDetails} See ${logs} to see the logs of this invocation.","messagePattern":"Lambda function (.+?) failed with an unhandled error: (.+?) See (.+?) to see the logs of this invocation\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/lambda-client/src/call-lambda-streaming.ts","lineNumber":151,"sourceCode":"\t}\n\n\tconst events =\n\t\tres.EventStream as AsyncIterable<InvokeWithResponseStreamResponseEvent>;\n\n\tfor await (const event of events) {\n\t\t// There are two types of events you can get on a stream.\n\n\t\t// `PayloadChunk`: These contain the actual raw bytes of the chunk\n\t\t// It has a single property: `Payload`\n\t\tif (event.PayloadChunk && event.PayloadChunk.Payload) {\n\t\t\tonData(event.PayloadChunk.Payload);\n\t\t}\n\n\t\tif (event.InvokeComplete) {\n\t\t\tif (event.InvokeComplete.ErrorCode) {\n\t\t\t\tconst 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}))`;\n\t\t\t\tif (event.InvokeComplete.ErrorCode === 'Unhandled') {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Lambda function ${functionName} failed with an unhandled error: ${\n\t\t\t\t\t\t\tevent.InvokeComplete.ErrorDetails as string\n\t\t\t\t\t\t} See ${logs} to see the logs of this invocation.`,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Lambda function ${functionName} failed with error code ${event.InvokeComplete.ErrorCode}: ${event.InvokeComplete.ErrorDetails}. See ${logs} to see the logs of this invocation.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\t// Don't put a `break` statement here, as it will cause the socket to not properly exit.\n\t}\n\n\t// @ts-expect-error - We are adding a listener to a global variable\n\tif (globalThis._dumpUnreleasedBuffers) {\n\t\t// @ts-expect-error - We are adding a listener to a global variable","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/lambda-client/src/call-lambda-streaming.ts#L133-L169","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nawait renderMediaOnLambda({ functionName: 'remotion-render', memorySizeInMb: 512 }); // OOM at cold start -> Unhandled\n\n// after\n// Redeploy with more memory and a fresh bundle\nawait deployFunction({ memorySizeInMb: 2048, timeoutInSeconds: 300 });\nawait renderMediaOnLambda({ functionName: 'remotion-render' });","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await renderMediaOnLambda({ ... });\n} catch (e) {\n  if (String((e as Error).message).includes('failed with an unhandled error')) {\n    // extract the CloudWatch URL from the message, open it, diagnose cold-start/init failure\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["lambda-client","streaming","aws-lambda","runtime-error","unhandled","cold-start","cloudwatch"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}