remotion-dev/remotion · error

Should not download a browser in serverless

Error message

Should not download a browser in serverless

What it means

In the serverless (Lambda) environment, a Chrome for Testing binary is already shipped with the function bundle, so downloading a browser at runtime is invalid. getBrowserInstanceImplementation wires onBrowserDownload to throw this error as a guard: if the launch flow ever attempts a download (e.g. the bundled binary is missing or chromeMode misconfigured), it fails with this clear message instead of attempting a download that cannot work in the sandbox.

Source

Thrown at packages/serverless/src/get-browser-instance.ts:140

		RenderInternals.Log.info(
			{indent: false, logLevel},
			'Cold function, launching new browser instance',
		);
		launching = true;

		try {
			const execPath = providerSpecifics.getChromiumPath();

			const instance = await RenderInternals.internalOpenBrowser({
				browser: 'chrome',
				browserExecutable: execPath,
				chromiumOptions: actualChromiumOptions,
				forceDeviceScaleFactor: undefined,
				indent: false,
				viewport: null,
				logLevel,
				onBrowserDownload: () => {
					throw new Error('Should not download a browser in serverless');
				},
				chromeMode: 'headless-shell',
			});
			const launchedBrowser = {
				instance,
				configurationString,
			};
			_browserInstance = launchedBrowser;
			instance.on('disconnected', () => {
				if (_browserInstance !== launchedBrowser) {
					return;
				}

				_browserInstance = null;
				RenderInternals.Log.info(
					{indent: false, logLevel},
					'Browser disconnected or crashed.',
				);

View on GitHub (pinned to b2f4e34732)

Solutions

1. Ensure the Chrome for Testing / headless-shell binary is included in the Lambda function bundle or layer (use the official Remotion Lambda layer / ensureChromeBrowsers included at deploy time)
2. Redeploy the function with the official npx remotion lambda functions deploy so binaries ship correctly
3. Check chromeMode configuration ('headless-shell' vs 'chrome') matches a binary that exists in the bundle
4. Verify package versions of @remotion/lambda, @remotion/renderer etc. are identical across client and function to avoid binary-path mismatches

Example fix

// before (custom bundle without browser)
const fn = await deployFunction({
  createFileSystemLayers: false,
  // zip built manually, chrome/ folder omitted
});
// after
const fn = await deployFunction({
  createFileSystemLayers: false,
  // zip includes node_modules/chrome-for-testing + headless shell as built by remotion lambda functions deploy
});

import {existsSync} from 'fs';
const shellPath = process.env.LAMBDA_TASK_ROOT + '/chrome-for-testing/headless-shell';
if (!existsSync(shellPath)) {
  throw new Error('Bundled headless-shell missing; redeploy the function with the Remotion Lambda layer.');
}

try {
  const browser = await getBrowserInstance();
} catch (err) {
  if (String(err).includes('Should not download a browser in serverless')) {
    throw new Error('Chrome binary missing from Lambda bundle. Redeploy via `npx remotion lambda functions deploy`.');
  }
  throw err;
}

When it happens

Trigger: Invoking a Lambda/serverless render where the browser launch path falls back to downloading a browser — typically because the bundled headless-shell/Chrome for Testing binary is missing from the Lambda layer or bundle, or the chromeMode setting does not resolve to an available binary.

Common situations: Deploying the Lambda function without the Chrome layer/binary; pruning the bundle so chromium is excluded; a Remotion version mismatch between the function bundle and client where the expected browser binary path changed; manually building the Lambda bundle without including Chrome for Testing.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Lambda function returned an error: {decoded_result['errorMes
• Fast Start finalization did not produce an output file
• Params must be renderer
• The version of the function that was specified as "rendererF
• Image format mismatch: ${outName} was given as the ${outName

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/b059ef2461f90bc9. Report an issue: GitHub.