{"record":{"id":"1d5aa69647bdeb2f","repo":"bevyengine/bevy","slug":"the-component-could-not-be-found","errorCode":null,"errorMessage":"the `Component` could not be found","messagePattern":"the `Component` could not be found","errorType":"exception","errorClass":"GetEntityMutByIdError","httpStatus":null,"severity":"error","filePath":"crates/bevy_ecs/src/world/unsafe_world_cell.rs","lineNumber":1229,"sourceCode":"                .entities()\n                .entity_get_spawned_or_despawned_unchecked(self.entity)\n                .1\n        }\n    }\n}\n\n/// Error that may be returned when calling [`UnsafeEntityCell::get_mut_by_id`].\n#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]\npub enum GetEntityMutByIdError {\n    /// The [`ComponentInfo`](crate::component::ComponentInfo) could not be found.\n    #[error(\"the `ComponentInfo` could not be found\")]\n    InfoNotFound,\n    /// The [`Component`] is immutable. Creating a mutable reference violates its\n    /// invariants.\n    #[error(\"the `Component` is immutable\")]\n    ComponentIsImmutable,\n    /// This [`Entity`] does not have the desired [`Component`].\n    #[error(\"the `Component` could not be found\")]\n    ComponentNotFound,\n}\n\nimpl<'w> UnsafeWorldCell<'w> {\n    #[inline]\n    /// # Safety\n    /// - the returned `Table` is only used in ways that this [`UnsafeWorldCell`] has permission for.\n    /// - the returned `Table` is only used in ways that would not conflict with any existing borrows of world data.\n    unsafe fn fetch_table(self, location: EntityLocation) -> Option<&'w Table> {\n        // SAFETY:\n        // - caller ensures returned data is not misused and we have not created any borrows of component/resource data\n        // - `location` contains a valid `TableId`, so getting the table won't fail\n        unsafe { self.storages().tables.get(location.table_id) }\n    }\n\n    #[inline]\n    /// # Safety\n    /// - the returned `ComponentSparseSet` is only used in ways that this [`UnsafeWorldCell`] has permission for.","sourceCodeStart":1211,"sourceCodeEnd":1247,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_ecs/src/world/unsafe_world_cell.rs#L1211-L1247","documentation":"GetEntityMutByIdError::ComponentNotFound is returned by UnsafeEntityCell::get_mut_by_id when the ComponentId is valid and known to the world, but this particular Entity does not have that component in its archetype/table. It is the by-id equivalent of world.get_mut::<T>(entity) returning None: entity alive, component absent.","triggerScenarios":"Calling get_mut_by_id(id) for a component the entity never had, had removed earlier in the frame (removal commands already flushed), or that lives only on entities matched by a different query; also after the component was swapped out via insert of a different bundle.","commonSituations":"Per-component dynamic access in unsafe code paths (relationship targets, dev-tools); assuming required components exist because a query elsewhere filters on them; races between removal observers and later by-id access in the same frame.","solutions":["Handle the None/Err case as normal control flow — this API returns Result<Option<_>, _> precisely so absence is not exceptional.","Pre-check with the typed API world.get::<T>(entity).is_some() or cell.get_by_id(id).is_some().","Ensure removal has not run: schedule the mutating access before the removing system, or apply/flush commands deliberately.","If the component is expected, verify the entity actually spawned the bundle containing it."],"exampleFix":"// before\nlet mut c = cell.get_mut_by_id(id).unwrap().unwrap(); // ComponentNotFound\n\n// after\nmatch cell.get_mut_by_id(id) {\n    Ok(Some(mut c)) => { /* mutate */ }\n    Ok(None) => debug!(\"entity lacks component {id:?}\"),\n    Err(GetEntityMutByIdError::ComponentNotFound) => unreachable!(),\n    Err(e) => debug!(\"{e}\"),\n}","handlingStrategy":"try-catch","validationCode":"let has = cell\n    .world()\n    .get_by_id(cell.id(), component_id)\n    .is_some();","typeGuard":null,"tryCatchPattern":"match cell.get_mut_by_id(component_id) {\n    Ok(Some(mut c)) => { /* mutate */ }\n    Ok(None) => { /* entity lacks component: skip */ }\n    Err(GetEntityMutByIdError::ComponentNotFound) => unreachable!(),\n    Err(e) => { /* InfoNotFound / ComponentIsImmutable handling */ }\n}","preventionTips":["Model absence as normal: Ok(None) / ComponentNotFound is expected for optional components.","Pre-check with get_by_id when the access pattern tolerates missing components.","Schedule by-id mutations before any system that removes those components."],"tags":["bevy","ecs","unsafe-world-cell","component","entity"],"backgroundTag":"component-not-found","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"}