Debugging failed Lambda renders

General debugging strategy

<Step>1</Step> Reproduce a render via the npx remotion lambda render command.

Use --props to pass in a JSON file with the same input props as the render you want to debug.
Use --log=verbose to get detailed debugging information.

<div> <Step>2</Step> Wait for the render to fully time out or throw an error. </div> <Step>3</Step> Read the error message carefully and use the log links that were printed.

Reasons a render may fail

There are four reasons renders may fail:

<Step>1</Step> An error occurs in your React code.
<Step>2</Step> A timeout occurs after calling delayRender().
<Step>3</Step> The Lambda function rendering one of the chunks times out.
<Step>4</Step> The main Lambda function times out.

Error in React code

If your code throws an error, you will see the error in the logs. If you are rendering via the CLI, the error will be symbolicated which can help you find the error in your code. Try to fix the error, redeploy the site and re-render.

Timeouts

Understanding which timeout occurred

If your error message reads that a delayRender() call timed out, a function has called delayRender() but did not call continueRender() within the timeout period. This is usually caused by a bug in your code. See Debugging timeout for more tips.

:::note You can increase the timeout by passing timeoutInMilliseconds to renderMediaOnLamba() or passing --timeout to the CLI when rendering a video. Don't confuse it with the --timeout flag for the CLI when deploying a function (see below). :::

If your error message reads that the main Lambda function has timed out, it means that the render was still ongoing, but the maximum execution duration of the Lambda function has been hit. This is caused by either:

A render that takes too long to complete within the specified duration. In that case, you should increase the function timeout by passing --timeout to the CLI when deploying a function.
A render that has a bottleneck and completes slowly on Lambda. In that case, you should identify the bottleneck by measuring and optimizing the render. See Optimizing for speed for more tips.
A chunk is getting stuck, making it impossible for the main function to complete the task of concatenating the chunks. You should identify the chunk that is getting stuck by looking at the logs. See below for how to do this.

Inspecting the logs

<Step>1</Step> Get the Log URL:

If you use the CLI, add --log=verbose to the command. This will print a CloudWatch link to the console.
When using renderMediaOnLambda() add logLevel: "verbose" as an option. You will get a cloudWatchLogs field in the return value.

Open this link and log into AWS if needed. A log stream will open.

By default, the filter is set to:

"method=renderer,renderId=[render-id]"

Find the logs of a specific chunk

Tweak the query to find the logs of a specific chunk:

method=renderer,renderId=[render-id],chunk=12

will for example find the log stream of chunk 12. If your viewport is big enough, you will also see the chunk numbers in the summary view straight away.

Click the blue link in the Log stream name column to open the log stream. If you don't see any blue links, click "Display", then select "View in columns with details".

In the logstream, you will see debug logging from Remotion as well as any console.log statements from your React code.

Find the logs of the main function

Tweak the query to find the logs of the main function:

method=launch,renderId=[render-id]

You should get one result. Click the blue link in the Log stream name column to open the log stream. If you don't see any blue links, click "Display", then select "View in columns with details".

Finding the chunk that failed

To find which chunks failed to render, add --log=verbose to the Lambda render while rendering via the CLI.
Look for the link pointing to progress.json.
When using renderMediaOnLambda(), you will get a folderInS3Console field in the return value, which you can open and locate the progress.json file therein.

Within the progress.json file, you will find a chunks array.
The chunks that are missing are the ones that failed to render.

After you've identified which chunks are missing, inspect the logs for that chunk to find the cause of the error.

Stuck chunks while loading media from Cloudflare R2

If one chunk remains running much longer than the others, check whether it is loading a remote video or audio file.

When using <Video> or <Audio> from @remotion/media, Remotion may load only the required byte ranges from the source file. This reduces data transfer, but a slow or uncached range request can make one chunk wait much longer than the rest of the render.

If your assets are served from Cloudflare R2:

Serve the assets through a custom domain with Cloudflare Cache enabled. The r2.dev development URL does not support caching.
Configure a Cloudflare Cache Rule for the media URLs. If the response header is CF-Cache-Status: DYNAMIC, the request was not served from Cloudflare Cache.
If the source video has long intervals between keyframes, consider re-encoding it with a shorter keyframe interval so seeking requires less data.

See Data transfer cost: Use an alternate CDN for storing assets for details.

To make a stalled media load fail before the Lambda function reaches its execution timeout, set delayRenderTimeoutInMilliseconds on the media component to a value below the Lambda function timeout. Use delayRenderRetries if the load should be retried.

Increasing the timeout

Note that two types of timeouts come into play in Remotion:

The delayRender() timeout. This is the timeout that is defined using --timeout when calling npx remotion lambda render or using timeoutInMilliseconds when calling renderMediaOnLambda().
The Lambda function timeout. This is the timeout that is defined using --timeout when calling npx remotion lambda functions deploy or using timeoutInSeconds when calling deployFunction().

Reporting an issue

You may report an issue on GitHub and Discord.

To share a reproducible render, share the progress.json that lies in the S3 folder of the failed render under renders/[render-id]/progress.json.

If you use renderMediaOnLambda(), this function returns a link folderInS3Console pointing you to the right location in the S3 console.

If you use npx remotion lambda render, add --log=verbose to print the link to the file in the S3 console.

If you include CloudWatch logs in your report, post the full logs (click "Load more messages" until there are no more to load.)