remotion-dev/remotion · 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

When installing an Element into a Browser Studio project, the installation name must be a lowercase identifier (letters, numbers, hyphens) without a file extension, and the on-disk element file must be named exactly '<installationName>.element.tsx'. If installationName contains an extension, invalid characters, or does not match the element file name, this error is thrown by getElementInstallPlanForProject.

Source

Thrown at packages/browser-studio/src/browser-studio-operations.ts:337

	element,
	installationName,
	project,
}: Parameters<BrowserStudioOperations['prepareElementInstall']>[0] & {
	project: VirtualProject;
}) => {
	const componentName =
		StudioProtocolInternals.getElementComponentNameFromSourceCode(
			element.sourceCode,
		);
	const elementFileName = StudioProtocolInternals.makeElementFileNameFromSlug(
		installationName ?? element.slug,
	);
	if (
		elementFileName === null ||
		(typeof installationName === 'string' &&
			elementFileName !== `${installationName}.element.tsx`)
	) {
		throw new Error(
			'Use a lowercase installation name with letters, numbers and hyphens, without a file extension.',
		);
	}

	if (componentName === null) {
		throw new Error('Invalid Element source');
	}

	const target =
		destination.type === 'current-composition'
			? await resolveCompositionComponentWithFile({
					compositionFile: destination.compositionFile,
					compositionId: destination.compositionId,
					environment: makeInMemoryInsertJsxElementCodemodEnvironment({
						project,
						svgMarkupToJsx,
					}),
				})

View on GitHub (pinned to b2f4e34732)

Solutions

1. Strip the '.element.tsx' extension and pass only the bare lowercase name (e.g. 'my-element')
2. Normalize the name to lowercase letters, numbers and hyphens only
3. Ensure the project actually contains a file named '<installationName>.element.tsx' matching the name
4. Check whether an earlier plan/derivation step should have produced the installation name and is passing raw user input

Example fix

// before
await installElement({installationName: 'MyElement.element.tsx'});
// after
await installElement({installationName: 'my-element'});

const isValidInstallationName = (name: string) =>
	/^[a-z0-9-]+$/.test(name) && !name.includes('.');
if (!isValidInstallationName(name)) throw new Error('Invalid installation name: ' + name);

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

try {
	await installElement({installationName});
} catch (err) {
	if ((err as Error).message.includes('lowercase installation name')) {
		installationName = installationName.replace(/\.element\.tsx$/, '').toLowerCase().replace(/[^a-z0-9-]/g, '-');
		await installElement({installationName});
	} else throw err;
}

When it happens

Trigger: Calling the Element install API with an installation name like 'MyElement.element.tsx' (extension included), 'my element' (space/uppercase), or a name that doesn't correspond to the existing '<name>.element.tsx' file found in the project.

Common situations: Passing a full filename instead of the bare name; passing a PascalCase component name where a kebab-case installation name is expected; a mismatch between the name and the element file that exists on disk.

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/f5733d5b8fb7e78e. Report an issue: GitHub.