remotion-dev/remotion · error

version must be an exact semantic version.

Error message

version must be an exact semantic version.

What it means

The WebMcp install tool accepts an optional version but requires an exact semver (major.minor.patch, optionally with prerelease/build). Ranges like ^5.0.0 or latest are rejected because installations must be reproducible.

Source

Thrown at packages/studio/src/components/WebMcp.tsx:419

						additionalProperties: false,
					},
					annotations: {readOnlyHint: false},
					execute: async ({packageName, version}) => {
						if (
							typeof packageName !== 'string' ||
							!isValidPackageName(packageName)
						) {
							throw new Error('packageName must be a valid npm package name.');
						}

						if (
							version !== undefined &&
							(typeof version !== 'string' ||
								!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(
									version,
								))
						) {
							throw new Error('version must be an exact semantic version.');
						}

						await installPackages([
							{
								name: packageName,
								version: typeof version === 'string' ? version : null,
							},
						]);
						markOptionalPackageInstalled(packageName);
						return {installed: true, packageName};
					},
				},
				{signal: controller.signal},
			),
			modelContext.registerTool(
				{
					name: 'transcribe_asset',
					title: 'Transcribe Studio asset',

View on GitHub (pinned to b2f4e34732)

Solutions

1. Pass an exact version string, e.g. '4.0.249'.
2. Look up the exact latest version via `npm view <pkg> version` and use that.
3. Omit the version argument entirely to install without pinning.
4. Format as major.minor.patch (prerelease suffixes allowed, e.g. '4.0.0-rc.1').

Example fix

// before
await tool.execute({packageName: 'remotion', version: '^4.0.0'});
// after
await tool.execute({packageName: 'remotion', version: '4.0.249'});

const EXACT_SEMVER = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
if (version !== undefined && !(typeof version === 'string' && EXACT_SEMVER.test(version))) {
  throw new Error('version must be an exact semver like 4.0.249');
}

const isExactSemver = (v: unknown): v is string =>
  typeof v === 'string' && /^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/.test(v);

try {
  await installTool({packageName, version});
} catch (e) {
  if (e.message.includes('exact semantic version')) {
    version = await npmViewVersion(packageName);
  }
}

When it happens

Trigger: Calling the install tool with version set to a range ('^4.0.0', '~5.x', '>1.0.0'), a tag ('latest'), or a non-string value.

Common situations: Agents copying package.json range syntax; users asking for 'latest'; typos like '5.0' missing the patch segment.

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

• packageName must be a valid npm package name.
• The artifact filename ${artifact.filename} was emitted more
• Composition ${compositionName} not found.
• visible must be a boolean.
• orientation must be either "horizontal" or "vertical".

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