{"record":{"id":"de956ba613e8fec4","repo":"remotion-dev/remotion","slug":"composition-source-changed-during-element-installation","errorCode":null,"errorMessage":"Composition source changed during Element installation","messagePattern":"Composition source changed during Element installation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/studio-server/src/preview-server/routes/insert-element.ts","lineNumber":349,"sourceCode":"\t\t\t\t);\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\t!hasExpectedFileState({\n\t\t\t\t\tactual: finalPlan.expectedFileState,\n\t\t\t\t\texpected: plan.expectedFileState,\n\t\t\t\t})\n\t\t\t) {\n\t\t\t\tthrow new Error('Element source changed during installation');\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\tcompositionCreation !== null &&\n\t\t\t\t(readFileSync(compositionCreation.registrationFilePath, 'utf-8') !==\n\t\t\t\t\tcompositionCreation.registrationFileOldContents ||\n\t\t\t\t\texistsSync(compositionCreation.componentFilePath))\n\t\t\t) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t'Composition source changed during Element installation',\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst nodePathMutation = broadcastSequenceNodePathMutation(\n\t\t\t\t[\n\t\t\t\t\t{\n\t\t\t\t\t\tabsolutePath: inserted.fileName,\n\t\t\t\t\t\tremappings: inserted.nodePathRemappings,\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tnull,\n\t\t\t);\n\n\t\t\tpushTransactionToUndoStack({\n\t\t\t\tsnapshots: [\n\t\t\t\t\t...(compositionCreation === null\n\t\t\t\t\t\t? []","sourceCodeStart":331,"sourceCodeEnd":367,"githubUrl":"https://github.com/remotion-dev/remotion/blob/46a3a6bf13ca367376ff18bbb06dae2e87e0d068/packages/studio-server/src/preview-server/routes/insert-element.ts#L331-L367","documentation":"The Remotion Studio server detects, at the final step of installing an Element into a composition, that the composition's registration file contents no longer match what was read when the installation began, or that the component file now exists. This guard prevents inserting an Element into a composition whose source has been modified concurrently, which could produce a corrupted or inconsistent composition definition. The server aborts the mutation instead of applying it to stale contents.","triggerScenarios":"Calling the insert-element API route while the composition's registrationFilePath on disk differs from the recorded registrationFileOldContents, or while the target componentFilePath already exists on disk — i.e. the user (or an editor/HMR process) saved or created files during the Element installation.","commonSituations":"A developer edits and saves the composition file (e.g. in VS Code autosave) while Studio is installing an Element; a file watcher/formatter rewrites the registration file mid-operation; a partially completed previous install left the component file behind.","solutions":["Undo or re-save your composition edits so the registration file matches its pre-install state, then retry the Element installation","Delete the component file created by the interrupted install if you do not want it, then retry","Retry the insertion when the editor is idle and autosave/format-on-save is paused","Restart the Studio server so it re-reads current file state, then re-attempt the install"],"exampleFix":"// before: editing the composition while Studio inserts the Element\n// after: let the install finish before saving\n// 1. trigger the Element install in Studio\n// 2. do NOT save/modify the composition registration file until the install completes","handlingStrategy":"validation","validationCode":"// before triggering insert, compare current file to expected\nimport {readFileSync, existsSync} from 'fs';\nif (readFileSync(registrationFilePath, 'utf-8') !== expectedContents || existsSync(componentFilePath)) {\n  throw new Error('Composition source changed; resolve before inserting');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await insertElement(payload);\n} catch (e) {\n  if (e.message.includes('Composition source changed')) {\n    // refresh file state and retry\n  }\n}","preventionTips":["Pause editor autosave/format-on-save during Element installation","Do not edit composition files while Studio is inserting an Element","Remove leftover component files from failed installs before retrying"],"tags":["studio","filesystem","race-condition"],"backgroundTag":"invalid-state-transition","analyzedSha":"46a3a6bf13ca367376ff18bbb06dae2e87e0d068","analyzedAt":"2026-09-18T00:12:20.256Z","contentChangedAt":"2026-09-18T00:12:20.256Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}