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 is an older version. Deploy a new service with matchin version and use it to call renderMediaOnCloudRun().

What it means

Thrown server-side by renderMediaSingleThread() when the incoming request body has no clientVersion at all (body.clientVersion is undefined/null). This means the caller is using a client old enough to not send version metadata, so the deployed service cannot verify compatibility.

Source

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

import {getCompositionFromBody} from './helpers/get-composition-from-body';
import {getDownloadBehaviorSetting} from './helpers/get-download-behavior-setting';
import type {
	CloudRunPayloadType,
	RenderMediaOnCloudrunOutput,
} 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,
		)}`;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Upgrade @remotion/cloudrun to a version that sends clientVersion.
Redeploy the Cloud Run service to match your client version.
Avoid calling the Cloud Run endpoint with hand-crafted payloads lacking clientVersion.

Example fix

// before: outdated @remotion/cloudrun client
// after: upgrade and redeploy
npm install @remotion/cloudrun@latest
npx remotion cloudrun services deploy --region=us-central1

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.REMOTION_CLIENT_VERSION) {
  throw new Error('@remotion/cloudrun client is too old to send clientVersion; upgrade');
}

Prevention

Upgrade @remotion/cloudrun to a version that sends clientVersion.
Redeploy the service to the same version as the client.

When it happens

Trigger: A render request reaches the Cloud Run function with body.clientVersion falsy while body.type === 'media' and the service VERSION differs from the missing client version.

Common situations: Using a very old @remotion/cloudrun client that predates the clientVersion field, or a third-party tool posting render requests without version metadata.

Related errors

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