{"record":{"id":"b059ef2461f90bc9","repo":"remotion-dev/remotion","slug":"should-not-download-a-browser-in-serverless","errorCode":null,"errorMessage":"Should not download a browser in serverless","messagePattern":"Should not download a browser in serverless","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/serverless/src/get-browser-instance.ts","lineNumber":140,"sourceCode":"\t\tRenderInternals.Log.info(\n\t\t\t{indent: false, logLevel},\n\t\t\t'Cold function, launching new browser instance',\n\t\t);\n\t\tlaunching = true;\n\n\t\ttry {\n\t\t\tconst execPath = providerSpecifics.getChromiumPath();\n\n\t\t\tconst instance = await RenderInternals.internalOpenBrowser({\n\t\t\t\tbrowser: 'chrome',\n\t\t\t\tbrowserExecutable: execPath,\n\t\t\t\tchromiumOptions: actualChromiumOptions,\n\t\t\t\tforceDeviceScaleFactor: undefined,\n\t\t\t\tindent: false,\n\t\t\t\tviewport: null,\n\t\t\t\tlogLevel,\n\t\t\t\tonBrowserDownload: () => {\n\t\t\t\t\tthrow new Error('Should not download a browser in serverless');\n\t\t\t\t},\n\t\t\t\tchromeMode: 'headless-shell',\n\t\t\t});\n\t\t\tconst launchedBrowser = {\n\t\t\t\tinstance,\n\t\t\t\tconfigurationString,\n\t\t\t};\n\t\t\t_browserInstance = launchedBrowser;\n\t\t\tinstance.on('disconnected', () => {\n\t\t\t\tif (_browserInstance !== launchedBrowser) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\t_browserInstance = null;\n\t\t\t\tRenderInternals.Log.info(\n\t\t\t\t\t{indent: false, logLevel},\n\t\t\t\t\t'Browser disconnected or crashed.',\n\t\t\t\t);","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/serverless/src/get-browser-instance.ts#L122-L158","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","Redeploy the function with the official npx remotion lambda functions deploy so binaries ship correctly","Check chromeMode configuration ('headless-shell' vs 'chrome') matches a binary that exists in the bundle","Verify package versions of @remotion/lambda, @remotion/renderer etc. are identical across client and function to avoid binary-path mismatches"],"exampleFix":"// before (custom bundle without browser)\nconst fn = await deployFunction({\n  createFileSystemLayers: false,\n  // zip built manually, chrome/ folder omitted\n});\n// after\nconst fn = await deployFunction({\n  createFileSystemLayers: false,\n  // zip includes node_modules/chrome-for-testing + headless shell as built by remotion lambda functions deploy\n});","handlingStrategy":"validation","validationCode":"import {existsSync} from 'fs';\nconst shellPath = process.env.LAMBDA_TASK_ROOT + '/chrome-for-testing/headless-shell';\nif (!existsSync(shellPath)) {\n  throw new Error('Bundled headless-shell missing; redeploy the function with the Remotion Lambda layer.');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const browser = await getBrowserInstance();\n} catch (err) {\n  if (String(err).includes('Should not download a browser in serverless')) {\n    throw new Error('Chrome binary missing from Lambda bundle. Redeploy via `npx remotion lambda functions deploy`.');\n  }\n  throw err;\n}","preventionTips":["Deploy Lambda functions with the official `npx remotion lambda functions deploy` so Chrome for Testing ships in the bundle","Never rely on runtime browser downloads inside Lambda; binaries must be pre-bundled","Keep @remotion/lambda, @remotion/renderer and @remotion/compositor-* versions in sync","Confirm chromeMode ('headless-shell' or 'chrome') matches a binary present in the deployed layer"],"tags":["lambda","chromium","browser-download","serverless"],"backgroundTag":"unsupported-platform","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}