What causes "Should not download a browser in Cloud Run" in remotion-dev/remotion?

Redeploy the Cloud Run service using the standard deploy command.

remotion-dev/remotion · critical · Error

Should not download a browser in Cloud Run

Error message

Should not download a browser in Cloud Run

What it means

Thrown inside renderMediaSingleThread() if the headless browser used for the render attempts to download its binary. Cloud Run services bundle a headless-shell browser at deploy time, so a download attempt signals the bundled binary is missing or the browser path is misconfigured.

Source

Thrown at packages/cloudrun/src/functions/render-media-single-thread.ts:208

			onCtrlCExit: () => undefined,
			onDownload: () => undefined,
			onStart: () => undefined,
			overwrite: true,
			port: null,
			preferLossless: body.preferLossless,
			puppeteerInstance: undefined,
			server: undefined,
			offthreadVideoCacheSizeInBytes: body.offthreadVideoCacheSizeInBytes,
			mediaCacheSizeInBytes: body.mediaCacheSizeInBytes,
			offthreadVideoThreads: body.offthreadVideoThreads,
			colorSpace: body.colorSpace,
			repro: false,
			binariesDirectory: null,
			separateAudioTo: null,
			forSeamlessAacConcatenation: false,
			compositionStart: 0,
			onBrowserDownload: () => {
				throw new Error('Should not download a browser in Cloud Run');
			},
			onArtifact,
			metadata: body.metadata ?? null,
			hardwareAcceleration: 'disable',
			chromeMode: 'headless-shell',
			onLog: RenderInternals.defaultOnLog,
			licenseKey: null,
			isProduction: null,
			sampleRate: body.sampleRate ?? 48000,
		});

		const storage = new Storage();

		const publicUpload = body.privacy === 'public' || !body.privacy;

		const uploadedResponse = await storage
			.bucket(body.outputBucket)
			.upload(tempFilePath, {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Redeploy the Cloud Run service using the standard deploy command.
Avoid using custom Docker images that strip the bundled browser.
Ensure no env var overrides the browser path on the service.

Example fix

// no user code fix; server-side invariant
// redeploy the service:
// npx remotion cloudrun services deploy --region=us-central1 --memory=2Gi

Defensive patterns

Strategy: retry

Prevention

Use the standard deploy command so the bundled headless-shell is present.
Do not deploy custom images that remove the browser binary.
Redeploy if renders start failing with this invariant.

When it happens

Trigger: The onBrowserDownload callback fires during internalRenderMedia(), meaning the system could not locate the pre-installed browser and tried to fetch one.

Common situations: Corrupted or misconfigured Cloud Run service image, deploying a custom image without the bundled browser, or a runtime path issue.

Related errors

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/90ebd0beedff4e77. Report an issue: GitHub.