remotion-dev/remotion · error · Error

Use a lowercase installation name with letters, numbers and

Error message

Use a lowercase installation name with letters, numbers and hyphens, without a file extension.

What it means

getElementInstallPlan validates the installation name for a Remotion Element being installed into a project. The derived source file must be '<installationName>.element.tsx'; if the file name could not be derived or does not match the installation name, the name is considered invalid and this error is thrown. Installation names must be lowercase with letters, numbers and hyphens and carry no file extension.

Source

Thrown at packages/studio-server/src/preview-server/routes/element-install-plan.ts:151

					remotionRoot,
					compositionFile: destination.compositionFile,
					compositionId: destination.compositionId,
				})
			: null;
	if (location !== null && !location.canAddSequence) {
		throw new Error('Cannot insert Element into this composition component');
	}

	const derivedElementFileName =
		StudioProtocolInternals.makeElementFileNameFromSlug(
			installationName ?? element.slug,
		);
	if (
		derivedElementFileName === null ||
		(typeof installationName === 'string' &&
			derivedElementFileName !== `${installationName}.element.tsx`)
	) {
		throw new Error(
			'Use a lowercase installation name with letters, numbers and hyphens, without a file extension.',
		);
	}

	const destinationCompositionFile = destination.compositionFile;
	const destinationCompositionFileName =
		destinationCompositionFile === null
			? (await getProjectInfo(remotionRoot, entryPoint)).rootFile
			: path.resolve(remotionRoot, destinationCompositionFile);
	if (destinationCompositionFileName === null) {
		throw new Error('Could not find the root file of the project');
	}

	const compositionFileName =
		location?.fileName ?? destinationCompositionFileName;

	const safePaths = await getSafeElementInstallPaths({
		compositionFileName,

View on GitHub (pinned to b2f4e34732)

Solutions

1. Use a lowercase installation name containing only letters, numbers and hyphens, with no file extension (e.g. 'my-cool-element').
2. Remove any '.tsx' / '.element.tsx' suffix you may have included in the name.
3. Verify the element source actually contains a file named '<name>.element.tsx' matching the installation name; use the element's canonical name.
4. Check for typos or accidental path segments in the installationName input.

Example fix

// before
await getElementInstallPlan({installationName: 'MyCoolElement.tsx'});
// after
await getElementInstallPlan({installationName: 'my-cool-element'});

if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(installationName)) {
  throw new Error('installationName must be lowercase letters, numbers and hyphens');
}

const isValidInstallName = (n: unknown): n is string =>
  typeof n === 'string' && /^[a-z0-9]+(-[a-z0-9]+)*$/.test(n);

try {
  const plan = await getElementInstallPlan(input);
} catch (e) {
  if (e.message.startsWith('Use a lowercase installation name')) {
    input.installationName = input.installationName.toLowerCase().replace(/[^a-z0-9-]/g, '-');
  } else throw e;
}

When it happens

Trigger: Calling the element install plan API with an installationName containing uppercase letters, underscores, dots/extension (e.g. 'MyElement' or 'my.element'), or when the fetched element's file name does not match '<installationName>.element.tsx'.

Common situations: Pasting a URL or element ID with mixed case, including '.tsx' or '.element.tsx' in the name field, or installing an element whose source repository file name diverges from the requested name.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Use a lowercase installation name with letters, numbers and
• The bucketName parameter must start with ${REMOTION_BUCKET_P
• The bucket ${bucketName}
• The `siteName` must match the RegExp `/^[-0-9a-zA-Z!_.*'()]+
• Composition id can only contain a-z, A-Z, 0-9, CJK character

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