remotion-dev/remotion · error · Error

Version mismatch: When calling renderMediaOnCloudRun(), you

Error message

Version mismatch: When calling renderMediaOnCloudRun(), you called a service, which has the version ${VERSION}, but the @remotion/cloudrun package you used to invoke the function has version ${body.clientVersion}. Deploy a new service and use it to call renderMediaOnCloudrun().

What it means

Thrown server-side by renderMediaSingleThread() when body.clientVersion is present but does not match the deployed service's VERSION. The service and the @remotion/cloudrun client must be on the same version to guarantee API compatibility.

Source

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

} from './helpers/payloads';
import {writeCloudrunError} from './helpers/write-cloudrun-error';

export const renderMediaSingleThread = async (
	body: CloudRunPayloadType,
	res: ff.Response,
) => {
	if (body.type !== 'media') {
		throw new Error('expected type media');
	}

	if (body.clientVersion !== VERSION) {
		if (!body.clientVersion) {
			throw new Error(
				`Version mismatch: When calling renderMediaOnCloudRun(), you called a service which has the version ${VERSION} but the @remotion/cloudrun package is an older version. Deploy a new service with matchin version and use it to call renderMediaOnCloudRun().`,
			);
		}

		throw new Error(
			`Version mismatch: When calling renderMediaOnCloudRun(), you called a service, which has the version ${VERSION}, but the @remotion/cloudrun package you used to invoke the function has version ${body.clientVersion}. Deploy a new service and use it to call renderMediaOnCloudrun().`,
		);
	}

	const renderId = body.renderIdOverride ?? randomHash({randomInTests: true});

	try {
		const composition = await getCompositionFromBody(body);

		const defaultOutName = `out.${RenderInternals.getFileExtensionFromCodec(
			body.codec,
			body.audioCodec,
		)}`;
		const tempFilePath = `/tmp/${defaultOutName}`;

		let previousProgress = 0.02;
		let lastWebhookProgress = 0;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Redeploy the Cloud Run service: npx remotion cloudrun services deploy.
Align client and service versions: npm install @remotion/cloudrun@<service-version>.
Run npx remotion cloudrun services ls to inspect deployed versions.

Example fix

// before: client is 5.0.0, service is 4.0.0
// after: redeploy to match client
npx remotion cloudrun services deploy --region=us-central1
// or pin client to service version
npm install @remotion/cloudrun@4.0.0

Defensive patterns

Strategy: validation

Validate before calling

import {VERSION} from '@remotion/cloudrun';
const services = await listServices(region);
const matching = services.find(s => parseServiceName(s).remotionVersion === VERSION);
if (!matching) throw new Error('No service matching client version ' + VERSION);

Try / catch

try {
  await renderMediaOnCloudRun({serviceName, region, ...});
} catch (e) {
  if (e.message.startsWith('Version mismatch')) {
    // redeploy service or pin client version
  }
  throw e;
}

Prevention

Redeploy the Cloud Run service whenever you bump @remotion/cloudrun.
Pin client and service to the same version in CI.
Use `remotion cloudrun services ls` to audit deployed versions.

When it happens

Trigger: A render request carries body.clientVersion = X but the deployed service runs VERSION = Y (X !== Y).

Common situations: Upgrading @remotion/cloudrun in the client without redeploying the Cloud Run service, or deploying a new service while an old client invokes it.

Related errors

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