What causes "packageName must be a valid npm package name." in remotion-dev/remotion?

Pass a valid npm package name, e.g. '@remotion/whisper-webgpu' or 'remotion'.

packageName must be a valid npm package name.

Error message

packageName must be a valid npm package name.

What it means

The WebMcp package-install tool validates packageName with isValidPackageName before installing. An invalid or non-string name is rejected to prevent installing malformed or malicious npm identifiers.

Source

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

								type: 'string',
								description: 'The npm package name to install.',
							},
							version: {
								type: 'string',
								description:
									'An optional exact semantic version. Omit it to use the recommended version.',
							},
						},
						required: ['packageName'],
						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,
							},
						]);

View on GitHub (pinned to b2f4e34732)

Solutions

Pass a valid npm package name, e.g. '@remotion/whisper-webgpu' or 'remotion'.
Verify the name on npm (lowercase, URL-safe, valid scoped form).
Ensure the argument is a string, not null/undefined.
If installing a local package, publish or pack it first — only npm names are accepted.

Example fix

// before
await tool.execute({packageName: 'Remotion'});
// after
await tool.execute({packageName: 'remotion'});

Defensive patterns

Strategy: validation

Validate before calling

const isValidPackageName = (name: unknown): name is string =>
  typeof name === 'string' && /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);

Type guard

const isNpmName = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0 && v === v.toLowerCase() && !v.includes(' ');

Try / catch

try {
  await installTool({packageName});
} catch (e) {
  if (e.message.includes('valid npm package name')) {
    suggestCorrectNpmName(packageName);
  }
}

Prevention

Use lowercase, valid npm identifiers.
Copy package names from npm search results.
Never pass paths or URLs as packageName.

When it happens

Trigger: Calling the install tool with packageName missing, not a string, or failing npm name rules (e.g. uppercase, spaces, leading dots/underscores, empty, scoped name typos like '@scope' without slash).

Common situations: MCP agents passing guessed package names; typos like 'remotion '` or 'Remotion'; attempting to install a local path or git URL instead of an npm name.

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

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