Make system param validation rely on the unified ECS error handling via the GLOBAL_ERROR_HANDLER (#18454)

There are two related problems here:

1. Users should be able to change the fallback behavior of *all*
ECS-based errors in their application by setting the
`GLOBAL_ERROR_HANDLER`. See #18351 for earlier work in this vein.
2. The existing solution (#15500) for customizing this behavior is high
on boilerplate, not global and adds a great deal of complexity.

The consensus is that the default behavior when a parameter fails
validation should be set based on the kind of system parameter in
question: `Single` / `Populated` should silently skip the system, but
`Res` should panic. Setting this behavior at the system level is a
bandaid that makes getting to that ideal behavior more painful, and can
mask real failures (if a resource is missing but you've ignored a system
to make the Single stop panicking you're going to have a bad day).

I've removed the existing `ParamWarnPolicy`-based configuration, and
wired up the `GLOBAL_ERROR_HANDLER`/`default_error_handler` to the
various schedule executors to properly plumb through errors .

Additionally, I've done a small cleanup pass on the corresponding
example.

I've run the `fallible_params` example, with both the default and a
custom global error handler. The former panics (as expected), and the
latter spams the error console with warnings 🥲

1. Currently, failed system param validation will result in endless
console spam. Do you want me to implement a solution for warn_once-style
debouncing somehow?
2. Currently, the error reporting for failed system param validation is
very limited: all we get is that a system param failed validation and
the name of the system. Do you want me to implement improved error
reporting by bubbling up errors in this PR?
3. There is broad consensus that the default behavior for failed system
param validation should be set on a per-system param basis. Would you
like me to implement that in this PR?

My gut instinct is that we absolutely want to solve 2 and 3, but it will
be much easier to do that work (and review it) if we split the PRs
apart.

`ParamWarnPolicy` and the `WithParamWarnPolicy` have been removed
completely. Failures during system param validation are now handled via
the `GLOBAL_ERROR_HANDLER`: please see the `bevy_ecs::error` module docs
for more information.

---------

Co-authored-by: MiniaczQ <[email protected]>

Author: 2 people

Cargo.toml

@@ -2203,6 +2203,7 @@ wasm = false
 name = "fallible_params"
 path = "examples/ecs/fallible_params.rs"
 doc-scrape-examples = true
+required-features = ["configurable_error_handler"]
 
 [package.metadata.example.fallible_params]
 name = "Fallible System Parameters"

crates/bevy_ecs/src/error/handler.rs

@@ -15,6 +15,13 @@ pub enum ErrorContext {
         /// The last tick that the system was run.
         last_run: Tick,
     },
+    /// The error occurred in a run condition.
+    RunCondition {
+        /// The name of the run condition that failed.
+        name: Cow<'static, str>,
+        /// The last tick that the run condition was evaluated.
+        last_run: Tick,
+    },
     /// The error occurred in a command.
     Command {
         /// The name of the command that failed.
@@ -39,6 +46,9 @@ impl Display for ErrorContext {
             Self::Observer { name, .. } => {
                 write!(f, "Observer `{}` failed", name)
             }
+            Self::RunCondition { name, .. } => {
+                write!(f, "Run condition `{}` failed", name)
+            }
         }
     }
 }
@@ -49,7 +59,8 @@ impl ErrorContext {
         match self {
             Self::System { name, .. }
             | Self::Command { name, .. }
-            | Self::Observer { name, .. } => name,
+            | Self::Observer { name, .. }
+            | Self::RunCondition { name, .. } => name,
         }
     }
 
@@ -61,6 +72,7 @@ impl ErrorContext {
             Self::System { .. } => "system",
             Self::Command { .. } => "command",
             Self::Observer { .. } => "observer",
+            Self::RunCondition { .. } => "run condition",
         }
     }
 }

crates/bevy_ecs/src/lib.rs

@@ -93,7 +93,7 @@ pub mod prelude {
             Command, Commands, Deferred, EntityCommand, EntityCommands, In, InMut, InRef,
             IntoSystem, Local, NonSend, NonSendMut, ParamSet, Populated, Query, ReadOnlySystem,
             Res, ResMut, Single, System, SystemIn, SystemInput, SystemParamBuilder,
-            SystemParamFunction, WithParamWarnPolicy,
+            SystemParamFunction,
         },
         world::{
             EntityMut, EntityRef, EntityWorldMut, FilteredResources, FilteredResourcesMut,

crates/bevy_ecs/src/observer/runner.rs

@@ -7,7 +7,7 @@ use crate::{
     observer::{ObserverDescriptor, ObserverTrigger},
     prelude::*,
     query::DebugCheckedUnwrap,
-    system::{IntoObserverSystem, ObserverSystem},
+    system::{IntoObserverSystem, ObserverSystem, SystemParamValidationError},
     world::DeferredWorld,
 };
 use bevy_ptr::PtrMut;
@@ -416,6 +416,14 @@ fn observer_system_runner<E: Event, B: Bundle, S: ObserverSystem<E, B>>(
                 );
             };
             (*system).queue_deferred(world.into_deferred());
+        } else {
+            error_handler(
+                SystemParamValidationError.into(),
+                ErrorContext::Observer {
+                    name: (*system).name(),
+                    last_run: (*system).get_last_run(),
+                },
+            );
         }
     }
 }

crates/bevy_ecs/src/schedule/executor/mod.rs

@@ -314,7 +314,7 @@ mod tests {
     use crate::{
         prelude::{IntoScheduleConfigs, Resource, Schedule, SystemSet},
         schedule::ExecutorKind,
-        system::{Commands, Res, WithParamWarnPolicy},
+        system::Commands,
         world::World,
     };
 
@@ -346,8 +346,7 @@ mod tests {
                 // This system depends on a system that is always skipped.
                 (|mut commands: Commands| {
                     commands.insert_resource(R2);
-                })
-                .warn_param_missing(),
+                }),
             )
                 .chain(),
         );
@@ -358,35 +357,4 @@ mod tests {
 
     #[derive(SystemSet, Hash, Debug, PartialEq, Eq, Clone)]
     struct S1;
-
-    #[test]
-    fn invalid_condition_param_skips_system() {
-        for executor in EXECUTORS {
-            invalid_condition_param_skips_system_core(executor);
-        }
-    }
-
-    fn invalid_condition_param_skips_system_core(executor: ExecutorKind) {
-        let mut world = World::new();
-        let mut schedule = Schedule::default();
-        schedule.set_executor_kind(executor);
-        schedule.configure_sets(S1.run_if((|_: Res<R1>| true).warn_param_missing()));
-        schedule.add_systems((
-            // System gets skipped if system set run conditions fail validation.
-            (|mut commands: Commands| {
-                commands.insert_resource(R1);
-            })
-            .warn_param_missing()
-            .in_set(S1),
-            // System gets skipped if run conditions fail validation.
-            (|mut commands: Commands| {
-                commands.insert_resource(R2);
-            })
-            .warn_param_missing()
-            .run_if((|_: Res<R2>| true).warn_param_missing()),
-        ));
-        schedule.run(&mut world);
-        assert!(world.get_resource::<R1>().is_none());
-        assert!(world.get_resource::<R2>().is_none());
-    }
 }

crates/bevy_ecs/src/schedule/executor/multi_threaded.rs

@@ -14,11 +14,11 @@ use tracing::{info_span, Span};
 
 use crate::{
     archetype::ArchetypeComponentId,
-    error::{BevyError, ErrorContext, Result},
+    error::{default_error_handler, BevyError, ErrorContext, Result},
     prelude::Resource,
     query::Access,
     schedule::{is_apply_deferred, BoxedCondition, ExecutorKind, SystemExecutor, SystemSchedule},
-    system::ScheduleSystem,
+    system::{ScheduleSystem, SystemParamValidationError},
     world::{unsafe_world_cell::UnsafeWorldCell, World},
 };
 
@@ -536,6 +536,7 @@ impl ExecutorState {
         world: UnsafeWorldCell,
     ) -> bool {
         let mut should_run = !self.skipped_systems.contains(system_index);
+        let error_handler = default_error_handler();
 
         for set_idx in conditions.sets_with_conditions_of_systems[system_index].ones() {
             if self.evaluated_sets.contains(set_idx) {
@@ -582,6 +583,14 @@ impl ExecutorState {
             // - `update_archetype_component_access` has been called for system.
             let valid_params = unsafe { system.validate_param_unsafe(world) };
             if !valid_params {
+                error_handler(
+                    SystemParamValidationError.into(),
+                    ErrorContext::System {
+                        name: system.name(),
+                        last_run: system.get_last_run(),
+                    },
+                );
+
                 self.skipped_systems.insert(system_index);
             }
             should_run &= valid_params;
@@ -767,6 +776,8 @@ unsafe fn evaluate_and_fold_conditions(
     conditions: &mut [BoxedCondition],
     world: UnsafeWorldCell,
 ) -> bool {
+    let error_handler = default_error_handler();
+
     #[expect(
         clippy::unnecessary_fold,
         reason = "Short-circuiting here would prevent conditions from mutating their own state as needed."
@@ -779,6 +790,14 @@ unsafe fn evaluate_and_fold_conditions(
             //   required by the condition.
             // - `update_archetype_component_access` has been called for condition.
             if !unsafe { condition.validate_param_unsafe(world) } {
+                error_handler(
+                    SystemParamValidationError.into(),
+                    ErrorContext::System {
+                        name: condition.name(),
+                        last_run: condition.get_last_run(),
+                    },
+                );
+
                 return false;
             }
             // SAFETY:

crates/bevy_ecs/src/schedule/executor/simple.rs

@@ -8,10 +8,11 @@ use tracing::info_span;
 use std::eprintln;
 
 use crate::{
-    error::{BevyError, ErrorContext},
+    error::{default_error_handler, BevyError, ErrorContext},
     schedule::{
         executor::is_apply_deferred, BoxedCondition, ExecutorKind, SystemExecutor, SystemSchedule,
     },
+    system::SystemParamValidationError,
     world::World,
 };
 
@@ -88,6 +89,16 @@ impl SystemExecutor for SimpleExecutor {
             let system = &mut schedule.systems[system_index];
             if should_run {
                 let valid_params = system.validate_param(world);
+                if !valid_params {
+                    error_handler(
+                        SystemParamValidationError.into(),
+                        ErrorContext::System {
+                            name: system.name(),
+                            last_run: system.get_last_run(),
+                        },
+                    );
+                }
+
                 should_run &= valid_params;
             }
 
@@ -153,6 +164,8 @@ impl SimpleExecutor {
 }
 
 fn evaluate_and_fold_conditions(conditions: &mut [BoxedCondition], world: &mut World) -> bool {
+    let error_handler = default_error_handler();
+
     #[expect(
         clippy::unnecessary_fold,
         reason = "Short-circuiting here would prevent conditions from mutating their own state as needed."
@@ -161,6 +174,13 @@ fn evaluate_and_fold_conditions(conditions: &mut [BoxedCondition], world: &mut W
         .iter_mut()
         .map(|condition| {
             if !condition.validate_param(world) {
+                error_handler(
+                    SystemParamValidationError.into(),
+                    ErrorContext::RunCondition {
+                        name: condition.name(),
+                        last_run: condition.get_last_run(),
+                    },
+                );
                 return false;
             }
             __rust_begin_short_backtrace::readonly_run(&mut **condition, world)

crates/bevy_ecs/src/schedule/executor/single_threaded.rs

@@ -8,8 +8,9 @@ use tracing::info_span;
 use std::eprintln;
 
 use crate::{
-    error::{BevyError, ErrorContext},
+    error::{default_error_handler, BevyError, ErrorContext},
     schedule::{is_apply_deferred, BoxedCondition, ExecutorKind, SystemExecutor, SystemSchedule},
+    system::SystemParamValidationError,
     world::World,
 };
 
@@ -94,6 +95,15 @@ impl SystemExecutor for SingleThreadedExecutor {
             let system = &mut schedule.systems[system_index];
             if should_run {
                 let valid_params = system.validate_param(world);
+                if !valid_params {
+                    error_handler(
+                        SystemParamValidationError.into(),
+                        ErrorContext::System {
+                            name: system.name(),
+                            last_run: system.get_last_run(),
+                        },
+                    );
+                }
                 should_run &= valid_params;
             }
 
@@ -196,6 +206,8 @@ impl SingleThreadedExecutor {
 }
 
 fn evaluate_and_fold_conditions(conditions: &mut [BoxedCondition], world: &mut World) -> bool {
+    let error_handler: fn(BevyError, ErrorContext) = default_error_handler();
+
     #[expect(
         clippy::unnecessary_fold,
         reason = "Short-circuiting here would prevent conditions from mutating their own state as needed."
@@ -204,6 +216,13 @@ fn evaluate_and_fold_conditions(conditions: &mut [BoxedCondition], world: &mut W
         .iter_mut()
         .map(|condition| {
             if !condition.validate_param(world) {
+                error_handler(
+                    SystemParamValidationError.into(),
+                    ErrorContext::RunCondition {
+                        name: condition.name(),
+                        last_run: condition.get_last_run(),
+                    },
+                );
                 return false;
             }
             __rust_begin_short_backtrace::readonly_run(&mut **condition, world)