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.

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'});
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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;
}

Prevention

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


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

Appendix: source

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

	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 46a3a6bf13)