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 by the renderStillOnCloudRun() server code path inside the Cloud Run service. The onBrowserDownload callback is hard-coded to throw because the deployed service image is expected to ship with a pre-installed headless Chrome shell; reaching the download path means the bundled browser is missing, misconfigured, or the render internals unexpectedly tried to fetch one. This is a fail-fast guard to prevent a slow, blocked network call inside Cloud Run.

Source

Thrown at packages/cloudrun/src/functions/render-still-single-thread.ts:109

			envVariables: body.envVariables,
			chromiumOptions: actualChromiumOptions,
			frame: body.frame,
			logLevel: body.logLevel,
			browserExecutable: null,
			cancelSignal: null,
			indent: false,
			timeoutInMilliseconds: body.delayRenderTimeoutInMilliseconds,
			onBrowserLog: null,
			onDownload: null,
			overwrite: true,
			port: null,
			puppeteerInstance: null,
			server: undefined,
			offthreadVideoCacheSizeInBytes: body.offthreadVideoCacheSizeInBytes,
			offthreadVideoThreads: body.offthreadVideoThreads,
			binariesDirectory: null,
			onBrowserDownload: () => {
				throw new Error('Should not download a browser in Cloud Run');
			},
			onArtifact: () => {
				throw new Error('Emitting artifacts is not supported in Cloud Run');
			},
			chromeMode: 'headless-shell',
			mediaCacheSizeInBytes: body.mediaCacheSizeInBytes,
			onLog: RenderInternals.defaultOnLog,
			licenseKey: null,
			isProduction: null,
		});
		Log.info({indent: false, logLevel: body.logLevel}, 'Still rendered');

		const storage = new Storage();

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

		const uploadedResponse = await storage
			.bucket(body.outputBucket)

View on GitHub (pinned to 78fe4bb3fd)

Solutions

  1. Redeploy the Cloud Run service from the official @remotion/cloudrun image for your package version so the bundled headless-shell is present.
  2. If using a custom image, ensure the headless Chrome binary is installed and the binariesDirectory path inside the container resolves correctly.
  3. Pin the @remotion/cloudrun version so the image's bundled browser matches the renderer's expectations.
  4. Report the issue if it reproduces on a freshly deployed official image — the bundled browser should never need downloading.

Example fix

// before: custom Dockerfile strips browser binaries to shrink image
// RUN rm -rf /root/.cache/remotion  # <-- removes bundled Chrome
// after: keep the bundled browser layer; do not delete browser cache
Defensive patterns

Strategy: fallback

Validate before calling

// Server-side guard; pre-check on the client cannot fully prevent it. Validate the image is official before deploying.
import pkg from '@remotion/cloudrun/package.json';
console.assert(typeof pkg.version === 'string', 'cloudrun package version missing');

Type guard

function isOfficialImage(imageUrl: string): boolean {
  // Official images live under the remotion-dev Artifact Registry
  return imageUrl.includes('projects/remotion-dev/') || imageUrl.includes('regions/gcr.io/remotion-dev');
}

Try / catch

// Unrecoverable inside a single render; signal the user to redeploy.
try {
  await renderStillOnCloudRun(opts);
} catch (err) {
  if (err instanceof Error && err.message === 'Should not download a browser in Cloud Run') {
    throw new Error('Service image missing bundled browser. Redeploy from the official @remotion/cloudrun image.');
  }
  throw err;
}

Prevention

When it happens

Trigger: The Cloud Run service container's bundled Chrome/headless-shell binary is absent, has wrong permissions, or its lookup path resolves to nothing, causing @remotion/renderer to fall back to onBrowserDownload. Only reached during a still render (renderStillOnCloudRun).

Common situations: Using a custom or outdated service image that lacks the bundled browser; an image build step that pruned browser binaries to save space; a Chrome for Testing version mismatch in the image; running the service with a service account or filesystem layout that cannot read the bundled binary.

Related errors

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