{"record":{"id":"f4bb21b186f99573","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 as string} 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":170,"sourceCode":"\n\ttry {\n\t\tfor await (const event of events) {\n\t\t\t// There are two types of events you can get on a stream.\n\n\t\t\t// `PayloadChunk`: These contain the actual raw bytes of the chunk\n\t\t\t// It has a single property: `Payload`\n\t\t\tif (event.PayloadChunk && event.PayloadChunk.Payload) {\n\t\t\t\t// Awaiting applies backpressure to the response stream when the\n\t\t\t\t// payload is being streamed to a sink\n\t\t\t\tawait onData(event.PayloadChunk.Payload);\n\t\t\t}\n\n\t\t\tif (event.InvokeComplete) {\n\t\t\t\tif (event.InvokeComplete.ErrorCode) {\n\t\t\t\t\tconst {consoleDomain} = getAwsRegionMetadata(region as AwsRegion);\n\t\t\t\t\tconst logs = `https://${region}.${consoleDomain}/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\t\tif (event.InvokeComplete.ErrorCode === 'Unhandled') {\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`Lambda function ${functionName} failed with an unhandled error: ${\n\t\t\t\t\t\t\t\tevent.InvokeComplete.ErrorDetails as string\n\t\t\t\t\t\t\t} See ${logs} to see the logs of this invocation.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\n\t\t\t\t\tthrow new Error(\n\t\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\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Don't put a `break` statement here, as it will cause the socket to not properly exit.\n\t\t}\n\t} finally {\n\t\t// @ts-expect-error - We are adding a listener to a global variable\n\t\tif (globalThis._dumpUnreleasedBuffers) {\n\t\t\t// @ts-expect-error - We are adding a listener to a global variable","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/remotion-dev/remotion/blob/10db9de07356446fb0edb3c3ae211369b693d18b/packages/lambda-client/src/call-lambda-streaming.ts#L152-L188","documentation":"Raised by callLambdaWithStreamingResponse when the invoked Remotion Lambda returns an InvokeComplete event with ErrorCode 'Unhandled'. 'Unhandled' is AWS's marker for a crash the Lambda runtime itself could not catch: the process died (OOM, timeout kill, native crash) or an exception escaped the handler. The message embeds ErrorDetails plus a prebuilt CloudWatch Logs Insights URL filtered to this request ID.","triggerScenarios":"Any render/payload API call (renderMediaOnLambda, renderStillOnLambda, getRenderProgress bootstrap, etc.) where the Remotion function crashes: memoryLimitMb too low so Chromium is OOM-killed, timeoutInSeconds exceeded (Lambda enforces a hard cap), or an unhandled exception in the function runtime outside Remotion's handler try/catch.","commonSituations":"Rendering memory-heavy compositions with default 2048 MB; timeoutInSeconds larger than the function's configured timeout; a broken custom layer or incompatible architecture causing the runtime to die; transient AWS capacity issues killing the sandbox.","solutions":["Open the CloudWatch Logs Insights link in the error — it is pre-filtered to the exact request ID — and read the crash cause (Runtime.OutOfMemory, Task timed out after X seconds, etc.).","Redeploy the function with more memory (memoryLimitMb; more memory also means more CPU) or a higher timeout, respecting the 15-minute Lambda ceiling.","If the log shows a timeout, lower chunk size / concurrency or raise timeoutInSeconds on the render call so the function can finish within its own limit.","If it is a transient crash, retry the render; persistent crashes point at a reproducible composition/runtime problem (test the same composition locally)."],"exampleFix":"// before\nawait deployFunction({region, memoryLimitMb: 2048, timeoutInSeconds: 120});\nawait renderMediaOnLambda({/* heavy composition */});\n\n// after\nawait deployFunction({region, memoryLimitMb: 4096, timeoutInSeconds: 900});\nawait renderMediaOnLambda({/* heavy composition */, timeoutInSeconds: 890, concurrencyPerLambda: 2});","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await renderMediaOnLambda({...});\n} catch (e) {\n  if (e instanceof Error && e.message.includes('failed with an unhandled error')) {\n    // extract the CloudWatch link from e.message, open it,\n    // bump memoryLimitMb/timeout and retry once\n  } else throw e;\n}","preventionTips":["Deploy with memoryLimitMb >= 4096 and a timeout below the 15-minute Lambda ceiling for heavy compositions.","Keep a CloudWatch Logs Insights link (as embedded in this error) in your runbooks for instant triage.","Smoke-test new compositions at low concurrency before full renders to catch OOM patterns early.","Set render timeoutInSeconds below the function timeout so renders fail gracefully instead of the function being killed."],"tags":["aws","lambda","render","out-of-memory","timeout","cloudwatch"],"backgroundTag":"lambda-unhandled-invocation-error","analyzedSha":"10db9de07356446fb0edb3c3ae211369b693d18b","analyzedAt":"2026-08-22T21:45:17.748Z","contentChangedAt":"2026-08-22T21:45:17.748Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}