{"record":{"id":"f5733d5b8fb7e78e","repo":"remotion-dev/remotion","slug":"use-a-lowercase-installation-name-with-letters-nu","errorCode":null,"errorMessage":"Use a lowercase installation name with letters, numbers and hyphens, without a file extension.","messagePattern":"Use a lowercase installation name with letters, numbers and hyphens, without a file extension\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/browser-studio/src/browser-studio-operations.ts","lineNumber":337,"sourceCode":"\telement,\n\tinstallationName,\n\tproject,\n}: Parameters<BrowserStudioOperations['prepareElementInstall']>[0] & {\n\tproject: VirtualProject;\n}) => {\n\tconst componentName =\n\t\tStudioProtocolInternals.getElementComponentNameFromSourceCode(\n\t\t\telement.sourceCode,\n\t\t);\n\tconst elementFileName = StudioProtocolInternals.makeElementFileNameFromSlug(\n\t\tinstallationName ?? element.slug,\n\t);\n\tif (\n\t\telementFileName === null ||\n\t\t(typeof installationName === 'string' &&\n\t\t\telementFileName !== `${installationName}.element.tsx`)\n\t) {\n\t\tthrow new Error(\n\t\t\t'Use a lowercase installation name with letters, numbers and hyphens, without a file extension.',\n\t\t);\n\t}\n\n\tif (componentName === null) {\n\t\tthrow new Error('Invalid Element source');\n\t}\n\n\tconst target =\n\t\tdestination.type === 'current-composition'\n\t\t\t? await resolveCompositionComponentWithFile({\n\t\t\t\t\tcompositionFile: destination.compositionFile,\n\t\t\t\t\tcompositionId: destination.compositionId,\n\t\t\t\t\tenvironment: makeInMemoryInsertJsxElementCodemodEnvironment({\n\t\t\t\t\t\tproject,\n\t\t\t\t\t\tsvgMarkupToJsx,\n\t\t\t\t\t}),\n\t\t\t\t})","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/browser-studio/src/browser-studio-operations.ts#L319-L355","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Strip the '.element.tsx' extension and pass only the bare lowercase name (e.g. 'my-element')","Normalize the name to lowercase letters, numbers and hyphens only","Ensure the project actually contains a file named '<installationName>.element.tsx' matching the name","Check whether an earlier plan/derivation step should have produced the installation name and is passing raw user input"],"exampleFix":"// before\nawait installElement({installationName: 'MyElement.element.tsx'});\n// after\nawait installElement({installationName: 'my-element'});","handlingStrategy":"validation","validationCode":"const isValidInstallationName = (name: string) =>\n\t/^[a-z0-9-]+$/.test(name) && !name.includes('.');\nif (!isValidInstallationName(name)) throw new Error('Invalid installation name: ' + name);","typeGuard":"const isValidInstallationName = (name: unknown): name is string =>\n\ttypeof name === 'string' && /^[a-z0-9-]+$/.test(name);","tryCatchPattern":"try {\n\tawait installElement({installationName});\n} catch (err) {\n\tif ((err as Error).message.includes('lowercase installation name')) {\n\t\tinstallationName = installationName.replace(/\\.element\\.tsx$/, '').toLowerCase().replace(/[^a-z0-9-]/g, '-');\n\t\tawait installElement({installationName});\n\t} else throw err;\n}","preventionTips":["Always pass the bare name, never the filename with extension","Normalize user-provided names to kebab-case before calling install APIs","Verify the corresponding <name>.element.tsx file exists in the project first"],"tags":["validation","naming","elements"],"backgroundTag":"invalid-identifier-format","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}