{"record":{"id":"83b13cfd61d7cbb8","repo":"remotion-dev/remotion","slug":"version-mismatch-when-calling-rendermediaoncloudr-83b13c","errorCode":null,"errorMessage":"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().","messagePattern":"Version mismatch: When calling renderMediaOnCloudRun\\(\\), you called a service, which has the version (.+?), but the @remotion/cloudrun package you used to invoke the function has version (.+?)\\. Deploy a new service and use it to call renderMediaOnCloudrun\\(\\)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/cloudrun/src/functions/render-still-single-thread.ts","lineNumber":32,"sourceCode":"} from './helpers/payloads';\nimport {writeCloudrunError} from './helpers/write-cloudrun-error';\n\nexport const renderStillSingleThread = async (\n\tbody: CloudRunPayloadType,\n\tres: ff.Response,\n) => {\n\tif (body.type !== 'still') {\n\t\tthrow new Error('expected type still');\n\t}\n\n\tif (body.clientVersion !== VERSION) {\n\t\tif (!body.clientVersion) {\n\t\t\tthrow new Error(\n\t\t\t\t`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().`,\n\t\t\t);\n\t\t}\n\n\t\tthrow new Error(\n\t\t\t`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().`,\n\t\t);\n\t}\n\n\tconst renderId = body.renderIdOverride ?? randomHash({randomInTests: true});\n\n\ttry {\n\t\tLog.verbose(\n\t\t\t{indent: false, logLevel: body.logLevel},\n\t\t\t'Rendering still frame',\n\t\t\tbody,\n\t\t);\n\n\t\tconst composition = await getCompositionFromBody(body);\n\n\t\tLog.verbose(\n\t\t\t{indent: false, logLevel: body.logLevel},\n\t\t\t'Composition loaded',","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/cloudrun/src/functions/render-still-single-thread.ts#L14-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: app upgraded package but service not redeployed\nawait renderMediaOnCloudRun({ serviceName, region, serveUrl, composition, codec });\n// after: redeploy first, then call\n// $ npx remotion cloudrun services deploy\nawait renderMediaOnCloudRun({ serviceName, region, serveUrl, composition, codec });","handlingStrategy":"validation","validationCode":"import pkg from '@remotion/cloudrun/package.json';\nconst clientVersion = pkg.version;\n// before calling renderMediaOnCloudRun, confirm the deployed service tag equals clientVersion\nconst service = await getServiceInfo({ serviceName, region });\nif (!service.uri.includes(clientVersion) && !service.tags?.includes(clientVersion)) {\n  throw new Error(`Redeploy service: client=${clientVersion} service tag mismatch`);\n}","typeGuard":"function isVersionAligned(clientPkgVersion: string, deployedTag: string | undefined): boolean {\n  return typeof clientPkgVersion === 'string' && clientPkgVersion === deployedTag;\n}","tryCatchPattern":"// Version mismatches are not transient — do not retry. Surface to the user with the redeploy instruction.\ntry {\n  await renderMediaOnCloudRun(opts);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Version mismatch')) {\n    throw new Error('Redeploy your Cloud Run service with `npx remotion cloudrun services deploy`, then retry.');\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["version-mismatch","cloudrun","deployment","server-side"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}