remotion-dev/remotion · critical · 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 inside a deployed Cloud Run service when the @remotion/cloudrun package version used by the client to invoke renderMediaOnCloudRun() does not match the VERSION baked into the running service image. Remotion enforces exact client/server version parity so the request payload schema and rendering internals agree. The message also covers the legacy case where body.clientVersion is missing (pre-versioning client). Deploying a fresh service built from the same package version is the only supported resolution.

Source

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

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

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

	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 {
		Log.verbose(
			{indent: false, logLevel: body.logLevel},
			'Rendering still frame',
			body,
		);

		const composition = await getCompositionFromBody(body);

		Log.verbose(
			{indent: false, logLevel: body.logLevel},
			'Composition loaded',

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Run `npx remotion cloudrun services deploy` (or your deploy command) to rebuild the service from the currently installed @remotion/cloudrun version, then retry the render.
Verify client and service versions match by printing require('@remotion/cloudrun/package.json').version in your app and comparing it to the service's deployed tag.
If you cannot redeploy immediately, downgrade your local @remotion/cloudrun to the version matching the running service (check the service tag in the GCP console).
Ensure body.clientVersion is populated — do not strip or override it in a custom caller; always invoke through the official renderMediaOnCloudRun() entry point.

Example fix

// before: app upgraded package but service not redeployed
await renderMediaOnCloudRun({ serviceName, region, serveUrl, composition, codec });
// after: redeploy first, then call
// $ npx remotion cloudrun services deploy
await renderMediaOnCloudRun({ serviceName, region, serveUrl, composition, codec });

Defensive patterns

Strategy: validation

Validate before calling

import pkg from '@remotion/cloudrun/package.json';
const clientVersion = pkg.version;
// before calling renderMediaOnCloudRun, confirm the deployed service tag equals clientVersion
const service = await getServiceInfo({ serviceName, region });
if (!service.uri.includes(clientVersion) && !service.tags?.includes(clientVersion)) {
  throw new Error(`Redeploy service: client=${clientVersion} service tag mismatch`);
}

Type guard

function isVersionAligned(clientPkgVersion: string, deployedTag: string | undefined): boolean {
  return typeof clientPkgVersion === 'string' && clientPkgVersion === deployedTag;
}

Try / catch

// Version mismatches are not transient — do not retry. Surface to the user with the redeploy instruction.
try {
  await renderMediaOnCloudRun(opts);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Version mismatch')) {
    throw new Error('Redeploy your Cloud Run service with `npx remotion cloudrun services deploy`, then retry.');
  }
  throw err;
}

Prevention

Treat service redeployment as part of the package upgrade workflow: bump @remotion/cloudrun, then redeploy.
Pin the same @remotion/cloudrun version across all environments and CI.
Print the package version and the deployed service tag in CI logs for quick diagnosis.

When it happens

Trigger: Client calls renderMediaOnCloudRun() against a service deployed from an older or newer @remotion/cloudrun release, so body.clientVersion differs from the service's VERSION constant. Also triggered when body.clientVersion is falsy (undefined/empty), which is the older-client branch.

Common situations: Upgrading @remotion/cloudrun in your app without redeploying the Cloud Run service; using a service a teammate deployed months ago; CI pinning a different package version than the one deployed; partial upgrade across monorepo packages.

Related errors

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