remotion-dev/remotion · error · Error

Invalid Remotion version.

Error message

Invalid Remotion version.

What it means

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.

Source

Thrown at packages/studio-server/src/preview-server/routes/upgrade-remotion.ts:14

import {spawn} from 'node:child_process';
import path from 'node:path';
import {RenderInternals} from '@remotion/renderer';
import type {ApiRoutes} from '@remotion/studio-shared';
import type {ApiHandler} from '../api-types';

let upgrading = false;

export const handleUpgradeRemotion: ApiHandler<
	ApiRoutes['/api/upgrade-remotion']['Request'],
	ApiRoutes['/api/upgrade-remotion']['Response']
> = async ({remotionRoot, logLevel, input: {version}}) => {
	if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version)) {
		throw new Error('Invalid Remotion version.');
	}

	if (upgrading) {
		throw new Error('A Remotion upgrade is already in progress.');
	}

	upgrading = true;
	try {
		const cliPackage = require.resolve('@remotion/cli/package.json', {
			paths: [remotionRoot],
		});
		const cli = path.join(path.dirname(cliPackage), 'remotion-cli.js');
		await new Promise<void>((resolve, reject) => {
			const child = spawn(
				process.execPath,
				[cli, 'upgrade', `--version=${version}`],
				{
					cwd: remotionRoot,

View on GitHub (pinned to b2f4e34732)

Solutions

1. Pass an exact semver version string like '4.0.2' with no leading 'v' or range operators.
2. Resolve 'latest' yourself (e.g. via npm view @remotion/cli version) before calling the API.
3. Ensure the client sends {version: string} in the request input.
4. Check for whitespace or invisible characters; trim the version string.

Example fix

// before
await api('/api/upgrade-remotion', {version: 'latest'});
// after
await api('/api/upgrade-remotion', {version: '4.0.218'});

if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version)) {
  throw new Error(`Invalid version for upgrade: ${version}`);
}

const isExactSemver = (v: unknown): v is string =>
  typeof v === 'string' && /^\d+\.\d+\.\d+$/.test(v);

try {
  await upgradeRemotion(version);
} catch (e) {
  if (e.message === 'Invalid Remotion version.') {
    version = await resolveLatestVersion(); // e.g. from npm registry
  } else throw e;
}

When it happens

Trigger: 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').

Common situations: Scripts passing an npm dist-tag or caret range instead of an exact version; clients built against older API shapes sending undefined version.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid ElevenLabs transcript. The transcript must be genera
• Parameter 'durationInMilliseconds' must be a number but got
• Parameter 'durationInMilliseconds' must not be NaN but it is
• Parameter 'durationInMilliseconds' must be finite but it is
• Parameter 'durationInMilliseconds' must be over 0 but it is

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/3b239ea09409b980. Report an issue: GitHub.