{"record":{"id":"830ecb48bbf44666","repo":"bevyengine/bevy","slug":"attempting-to-synchronize-an-entity-that-has-alrea","errorCode":null,"errorMessage":"Attempting to synchronize an entity that has already been synchronized!","messagePattern":"Attempting to synchronize an entity that has already been synchronized!","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/bevy_extract/src/sync_world.rs","lineNumber":233,"sourceCode":"pub(crate) struct PendingSyncEntity<L: AppLabel + Clone + Copy + Eq> {\n    #[deref]\n    records: Vec<EntityRecord<L>>,\n    marker: PhantomData<L>,\n}\n\npub(crate) fn entity_sync_system<L: AppLabel + Clone + Copy + Eq>(\n    main_world: &mut World,\n    sub_world: &mut World,\n) {\n    main_world.resource_scope(|world, mut pending: Mut<PendingSyncEntity<L>>| {\n        // TODO : batching record\n        for record in pending.drain(..) {\n            match record {\n                EntityRecord::Added(e) => {\n                    if let Ok(mut main_entity) = world.get_entity_mut(e) {\n                        match main_entity.entry::<SubEntity<L>>() {\n                            bevy_ecs::world::ComponentEntry::Occupied(_) => {\n                                panic!(\"Attempting to synchronize an entity that has already been synchronized!\");\n                            }\n                            bevy_ecs::world::ComponentEntry::Vacant(entry) => {\n                                let id = sub_world.spawn(MainEntity(e)).id();\n\n                                entry.insert(SubEntity::<L>(id, PhantomData));\n                            }\n                        };\n                    }\n                }\n                EntityRecord::Removed(sub_entity) => {\n                    if let Ok(ec) = sub_world.get_entity_mut(sub_entity.id()) {\n                        ec.despawn();\n                    };\n                }\n                EntityRecord::ComponentRemoved(main_entity, removal_function) => {\n                    let Some(sub_entity) = world.get::<SubEntity<L>>(main_entity) else {\n                        continue;\n                    };","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_extract/src/sync_world.rs#L215-L251","documentation":"This panic fires in bevy_extract's entity_sync_system while processing an EntityRecord::Added: the main-world entity to be synchronized already carries a SubEntity<L> component, meaning a sub-world counterpart was already spawned for it. The SyncWorldPlugin records Add<SyncToSubWorld> observations in PendingSyncEntity; if the same entity gets an 'added' record while its SubEntity link still exists, the sync machinery treats it as a double-synchronization bug and aborts.","triggerScenarios":"Removing and re-adding SyncToSubWorld (directly, or via removing/re-adding the ExtractComponentPlugin/SyncComponentPlugin machinery) on an entity whose SubEntity component was not cleaned up; running the sync system twice on the same PendingSyncEntity queue (double plugin registration with the same label L); manually inserting SubEntity onto entities; world state restored/duplicated while stale pending records remain.","commonSituations":"Adding SyncWorldPlugin::<SubApp>(default) twice or with the same AppLabel in multiple places; toggling extraction on an entity by removing/re-adding marker components each frame; snapshot/restore of the main World in editor hot-reload flows leaving both old SubEntity links and new Add records.","solutions":["Ensure SyncWorldPlugin (and the label L) is registered exactly once per App; check app.get_schedule_plugins or your plugin adder for duplicates.","Never remove SyncToSubWorld from a live entity — per its docs it should persist for the entity's entire lifecycle; despawn the entity instead.","Don't manually insert SubEntity; let the sync system own that component.","If restoring world state, clear PendingSyncEntity records and stale SubEntity components as part of the restore."],"exampleFix":"// before\neentity.remove::<SyncToSubWorld<SubApp>>(); // ... later re-add => double sync panic\napp.add_plugins(SyncWorldPlugin::<SubApp>::default());\napp.add_plugins(SyncWorldPlugin::<SubApp>::default()); // duplicate\n\n// after\n// keep the marker for the entity's lifetime; despawn instead of removing:\ncommands.entity(e).despawn();\n// and register the plugin once:\napp.add_plugins(SyncWorldPlugin::<SubApp>::default());","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep SyncToSubWorld on an entity for its entire lifecycle; despawn to end synchronization instead of removing the marker.","Register SyncWorldPlugin with a given AppLabel exactly once per App.","Never insert SubEntity components manually; the sync system owns them.","When snapshotting/restoring the main World, also clear PendingSyncEntity records and SubEntity links."],"tags":["bevy","extract","sync-world","sub-world","panic","plugin"],"backgroundTag":"duplicate-entity-synchronization","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}