{"record":{"id":"4d0298b454e709ed","repo":"remotion-dev/remotion","slug":"use-a-lowercase-installation-name-with-letters-nu-4d0298","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":"Error","httpStatus":null,"severity":"error","filePath":"packages/studio-server/src/preview-server/routes/element-install-plan.ts","lineNumber":151,"sourceCode":"\t\t\t\t\tremotionRoot,\n\t\t\t\t\tcompositionFile: destination.compositionFile,\n\t\t\t\t\tcompositionId: destination.compositionId,\n\t\t\t\t})\n\t\t\t: null;\n\tif (location !== null && !location.canAddSequence) {\n\t\tthrow new Error('Cannot insert Element into this composition component');\n\t}\n\n\tconst derivedElementFileName =\n\t\tStudioProtocolInternals.makeElementFileNameFromSlug(\n\t\t\tinstallationName ?? element.slug,\n\t\t);\n\tif (\n\t\tderivedElementFileName === null ||\n\t\t(typeof installationName === 'string' &&\n\t\t\tderivedElementFileName !== `${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\tconst destinationCompositionFile = destination.compositionFile;\n\tconst destinationCompositionFileName =\n\t\tdestinationCompositionFile === null\n\t\t\t? (await getProjectInfo(remotionRoot, entryPoint)).rootFile\n\t\t\t: path.resolve(remotionRoot, destinationCompositionFile);\n\tif (destinationCompositionFileName === null) {\n\t\tthrow new Error('Could not find the root file of the project');\n\t}\n\n\tconst compositionFileName =\n\t\tlocation?.fileName ?? destinationCompositionFileName;\n\n\tconst safePaths = await getSafeElementInstallPaths({\n\t\tcompositionFileName,","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/studio-server/src/preview-server/routes/element-install-plan.ts#L133-L169","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Use a lowercase installation name containing only letters, numbers and hyphens, with no file extension (e.g. 'my-cool-element').","Remove any '.tsx' / '.element.tsx' suffix you may have included in the name.","Verify the element source actually contains a file named '<name>.element.tsx' matching the installation name; use the element's canonical name.","Check for typos or accidental path segments in the installationName input."],"exampleFix":"// before\nawait getElementInstallPlan({installationName: 'MyCoolElement.tsx'});\n// after\nawait getElementInstallPlan({installationName: 'my-cool-element'});","handlingStrategy":"validation","validationCode":"if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(installationName)) {\n  throw new Error('installationName must be lowercase letters, numbers and hyphens');\n}","typeGuard":"const isValidInstallName = (n: unknown): n is string =>\n  typeof n === 'string' && /^[a-z0-9]+(-[a-z0-9]+)*$/.test(n);","tryCatchPattern":"try {\n  const plan = await getElementInstallPlan(input);\n} catch (e) {\n  if (e.message.startsWith('Use a lowercase installation name')) {\n    input.installationName = input.installationName.toLowerCase().replace(/[^a-z0-9-]/g, '-');\n  } else throw e;\n}","preventionTips":["Normalize names: lowercase, replace invalid chars with hyphens, strip extensions.","Never include '.tsx' or '.element.tsx' in the installation name.","Use the element's canonical/published name verbatim.","Validate the name with a regex before calling the API."],"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-14T00:17:10.932Z"}