{"record":{"id":"3b239ea09409b980","repo":"remotion-dev/remotion","slug":"invalid-remotion-version","errorCode":null,"errorMessage":"Invalid Remotion version.","messagePattern":"Invalid Remotion version\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/studio-server/src/preview-server/routes/upgrade-remotion.ts","lineNumber":14,"sourceCode":"import {spawn} from 'node:child_process';\nimport path from 'node:path';\nimport {RenderInternals} from '@remotion/renderer';\nimport type {ApiRoutes} from '@remotion/studio-shared';\nimport type {ApiHandler} from '../api-types';\n\nlet upgrading = false;\n\nexport const handleUpgradeRemotion: ApiHandler<\n\tApiRoutes['/api/upgrade-remotion']['Request'],\n\tApiRoutes['/api/upgrade-remotion']['Response']\n> = async ({remotionRoot, logLevel, input: {version}}) => {\n\tif (typeof version !== 'string' || !/^\\d+\\.\\d+\\.\\d+$/.test(version)) {\n\t\tthrow new Error('Invalid Remotion version.');\n\t}\n\n\tif (upgrading) {\n\t\tthrow new Error('A Remotion upgrade is already in progress.');\n\t}\n\n\tupgrading = true;\n\ttry {\n\t\tconst cliPackage = require.resolve('@remotion/cli/package.json', {\n\t\t\tpaths: [remotionRoot],\n\t\t});\n\t\tconst cli = path.join(path.dirname(cliPackage), 'remotion-cli.js');\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tconst child = spawn(\n\t\t\t\tprocess.execPath,\n\t\t\t\t[cli, 'upgrade', `--version=${version}`],\n\t\t\t\t{\n\t\t\t\t\tcwd: remotionRoot,","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/studio-server/src/preview-server/routes/upgrade-remotion.ts#L1-L32","documentation":"handleUpgradeRemotion validates the requested version string before starting an upgrade. Only semantic versions of the form X.Y.Z (digits and dots) are accepted. Anything else — ranges, 'latest', tags with prefixes, or non-string values — is rejected with this error.","triggerScenarios":"Calling the /api/upgrade-remotion endpoint with version missing, not a string, or not matching /^\\d+\\.\\d+\\.\\d+$/ (e.g. 'latest', 'v4.0.2', '4.0', '4.0.0-beta').","commonSituations":"Scripts passing an npm dist-tag or caret range instead of an exact version; clients built against older API shapes sending undefined version.","solutions":["Pass an exact semver version string like '4.0.2' with no leading 'v' or range operators.","Resolve 'latest' yourself (e.g. via npm view @remotion/cli version) before calling the API.","Ensure the client sends {version: string} in the request input.","Check for whitespace or invisible characters; trim the version string."],"exampleFix":"// before\nawait api('/api/upgrade-remotion', {version: 'latest'});\n// after\nawait api('/api/upgrade-remotion', {version: '4.0.218'});","handlingStrategy":"validation","validationCode":"if (typeof version !== 'string' || !/^\\d+\\.\\d+\\.\\d+$/.test(version)) {\n  throw new Error(`Invalid version for upgrade: ${version}`);\n}","typeGuard":"const isExactSemver = (v: unknown): v is string =>\n  typeof v === 'string' && /^\\d+\\.\\d+\\.\\d+$/.test(v);","tryCatchPattern":"try {\n  await upgradeRemotion(version);\n} catch (e) {\n  if (e.message === 'Invalid Remotion version.') {\n    version = await resolveLatestVersion(); // e.g. from npm registry\n  } else throw e;\n}","preventionTips":["Always pass an exact X.Y.Z version string, no tags or ranges.","Resolve dist-tags like 'latest' via the npm registry first.","Strip leading 'v' and trim whitespace from user input.","Store the target version in config rather than typing it ad hoc."],"tags":["validation","versioning","api"],"backgroundTag":"invalid-argument-format","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}