Update the ecs error handler to allow being updated more than once

Author: Brezak

crates/bevy_ecs/src/error/command_handling.rs

@@ -7,7 +7,7 @@ use crate::{
     world::{error::EntityMutableFetchError, World},
 };
 
-use super::{default_error_handler, BevyError, ErrorContext};
+use super::{get_error_handler, BevyError, ErrorContext};
 
 /// Takes a [`Command`] that returns a Result and uses a given error handler function to convert it into
 /// a [`Command`] that internally handles an error if it occurs and returns `()`.
@@ -21,7 +21,7 @@ pub trait HandleError<Out = ()> {
     where
         Self: Sized,
     {
-        self.handle_error_with(default_error_handler())
+        self.handle_error_with(get_error_handler())
     }
 }
 

crates/bevy_ecs/src/error/handler.rs

@@ -1,5 +1,3 @@
-#[cfg(feature = "configurable_error_handler")]
-use bevy_platform::sync::OnceLock;
 use core::fmt::Display;
 
 use crate::{component::Tick, error::BevyError};
@@ -77,53 +75,67 @@ impl ErrorContext {
     }
 }
 
-/// A global error handler. This can be set at startup, as long as it is set before
-/// any uses. This should generally be configured _before_ initializing the app.
-///
-/// This should be set inside of your `main` function, before initializing the Bevy app.
-/// The value of this error handler can be accessed using the [`default_error_handler`] function,
-/// which calls [`OnceLock::get_or_init`] to get the value.
-///
-/// **Note:** this is only available when the `configurable_error_handler` feature of `bevy_ecs` (or `bevy`) is enabled!
-///
-/// # Example
-///
-/// ```
-/// # use bevy_ecs::error::{GLOBAL_ERROR_HANDLER, warn};
-/// GLOBAL_ERROR_HANDLER.set(warn).expect("The error handler can only be set once, globally.");
-/// // initialize Bevy App here
-/// ```
-///
-/// To use this error handler in your app for custom error handling logic:
-///
-/// ```rust
-/// use bevy_ecs::error::{default_error_handler, GLOBAL_ERROR_HANDLER, BevyError, ErrorContext, panic};
-///
-/// fn handle_errors(error: BevyError, ctx: ErrorContext) {
-///    let error_handler = default_error_handler();
-///    error_handler(error, ctx);        
-/// }
-/// ```
-///
-/// # Warning
-///
-/// As this can *never* be overwritten, library code should never set this value.
+type BevyErrorHandler = fn(BevyError, ErrorContext);
+
 #[cfg(feature = "configurable_error_handler")]
-pub static GLOBAL_ERROR_HANDLER: OnceLock<fn(BevyError, ErrorContext)> = OnceLock::new();
+mod inner {
+    use super::*;
+    use core::sync::atomic::{AtomicPtr, Ordering};
 
-/// The default error handler. This defaults to [`panic()`],
-/// but if set, the [`GLOBAL_ERROR_HANDLER`] will be used instead, enabling error handler customization.
-/// The `configurable_error_handler` feature must be enabled to change this from the panicking default behavior,
-/// as there may be runtime overhead.
-#[inline]
-pub fn default_error_handler() -> fn(BevyError, ErrorContext) {
-    #[cfg(not(feature = "configurable_error_handler"))]
-    return panic;
+    // TODO: If we're willing to stomach the perf cost we could do a `RwLock<Box<dyn Fn(..)>>`.
+    static GLOBAL_ERROR_HANDLER: AtomicPtr<()> = AtomicPtr::new(core::ptr::null_mut());
 
-    #[cfg(feature = "configurable_error_handler")]
-    return *GLOBAL_ERROR_HANDLER.get_or_init(|| panic);
+    /// Gets the global error handler.
+    ///
+    /// If not set by [`set_error_handler`] defaults to [`panic()`].
+    pub fn get_error_handler() -> BevyErrorHandler {
+        // We need the acquire ordering since a sufficiently malicious user might call `set_error_handler`
+        // and immediately call `get_error_handler` so we need to make sure these loads and stores are synchronized
+        // with each other.
+        let handler = GLOBAL_ERROR_HANDLER.load(Ordering::Acquire);
+
+        if handler.is_null() {
+            panic
+        } else {
+            // SAFETY: We just checked if this is null and the only way to set this value is using `set_error_handler` which
+            //         makes sure this is actually a `BevyErrorHandler`.
+            unsafe { core::mem::transmute::<*mut (), BevyErrorHandler>(handler) }
+        }
+    }
+
+    /// Sets the error handler.
+    ///
+    /// This function is only available with the `configurable_error_handler` method enabled.
+    pub fn set_error_handler(hook: BevyErrorHandler) {
+        // Casting function pointers to normal pointers and back is called out as non-portable
+        // by the `mem::transmute` documentation. The problem is that on some architectures
+        // the size of a function pointers might be different from the size of a normal pointer.
+        //
+        // As of 2025-04-20 we're aware of 2 such architectures that also have a official rust target:
+        // - WebAssembly: This architecture explicitly allows casting functions to ints and back.
+        // - AVR:         The only official target with this architecture (avr-none) has a pointer width of 16.
+        //                Which we don't support.
+        //
+        // Additionally the rust `alloc` library uses the same trick for its allocation error hook and we require
+        // `alloc` support in this crate.
+        //
+        // AtomicFnPtr when?
+
+        // See `get_error_handler` for why we need `Ordering::Release`.
+        GLOBAL_ERROR_HANDLER.store(hook as *mut (), Ordering::Release);
+    }
+}
+
+#[cfg(not(feature = "configurable_error_handler"))]
+mod inner {
+    /// Gets the global error handler. This is currently [`panic()`].
+    pub fn get_error_handler() -> super::BevyErrorHandler {
+        super::panic
+    }
 }
 
+pub use inner::*;
+
 macro_rules! inner {
     ($call:path, $e:ident, $c:ident) => {
         $call!(
@@ -181,3 +193,42 @@ pub fn trace(error: BevyError, ctx: ErrorContext) {
 #[track_caller]
 #[inline]
 pub fn ignore(_: BevyError, _: ErrorContext) {}
+
+#[cfg(test)]
+mod tests {
+    #![allow(
+        clippy::allow_attributes,
+        reason = "We can't use except because the allow attribute becomes redundant in some cases."
+    )]
+
+    #[allow(
+        unused,
+        reason = "With the correct combination of features we might end up not compiling any tests."
+    )]
+    use super::*;
+
+    #[test]
+    // This test only makes sense under miri
+    #[cfg(miri)]
+    fn default_handler() {
+        // Check under miri that we aren't casting a null into a function pointer in the default case
+
+        // Don't trigger dead code elimination
+        core::hint::black_box(get_error_handler());
+    }
+
+    #[test]
+    #[cfg(feature = "configurable_error_handler")]
+    fn set_handler() {
+        // We need to cast the function into a pointer ahead of time. The function pointers were randomly different otherwise.
+        let new_handler = dont_handler_error as fn(_, _);
+
+        set_error_handler(new_handler);
+        let handler = get_error_handler();
+
+        assert_eq!(handler as *const (), new_handler as *const ());
+    }
+
+    #[cfg(feature = "configurable_error_handler")]
+    fn dont_handler_error(_: BevyError, _: ErrorContext) {}
+}

crates/bevy_ecs/src/error/mod.rs

@@ -8,7 +8,7 @@
 //! [`panic`] error handler function is used, resulting in a panic with the error message attached.
 //!
 //! You can change the default behavior by registering a custom error handler.
-//! Modify the [`GLOBAL_ERROR_HANDLER`] value to set a custom error handler function for your entire app.
+//! Use the [`set_error_handler`] method to set a custom error handler function for your entire app.
 //! In practice, this is generally feature-flagged: panicking or loudly logging errors in development,
 //! and quietly logging or ignoring them in production to avoid crashing the app.
 //!
@@ -36,7 +36,7 @@
 //! Remember to turn on the `configurable_error_handler` feature to set a global error handler!
 //!
 //! ```rust, ignore
-//! use bevy_ecs::error::{GLOBAL_ERROR_HANDLER, BevyError, ErrorContext};
+//! use bevy_ecs::error::{set_error_handler, BevyError, ErrorContext};
 //! use log::trace;
 //!
 //! fn my_error_handler(error: BevyError, ctx: ErrorContext) {
@@ -49,7 +49,7 @@
 //!
 //! fn main() {
 //!     // This requires the "configurable_error_handler" feature to be enabled to be in scope.
-//!     GLOBAL_ERROR_HANDLER.set(my_error_handler).expect("The error handler can only be set once.");
+//!     set_error_handler(my_error_handler);
 //!     
 //!     // Initialize your Bevy App here
 //! }

crates/bevy_ecs/src/observer/runner.rs

@@ -3,7 +3,7 @@ use core::any::Any;
 
 use crate::{
     component::{ComponentHook, ComponentId, HookContext, Mutable, StorageType},
-    error::{default_error_handler, ErrorContext},
+    error::{get_error_handler, ErrorContext},
     observer::{ObserverDescriptor, ObserverTrigger},
     prelude::*,
     query::DebugCheckedUnwrap,
@@ -458,7 +458,7 @@ fn hook_on_add<E: Event, B: Bundle, S: ObserverSystem<E, B>>(
             ..Default::default()
         };
 
-        let error_handler = default_error_handler();
+        let error_handler = get_error_handler();
 
         // Initialize System
         let system: *mut dyn ObserverSystem<E, B> =

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

@@ -14,7 +14,7 @@ use tracing::{info_span, Span};
 
 use crate::{
     archetype::ArchetypeComponentId,
-    error::{default_error_handler, BevyError, ErrorContext, Result},
+    error::{get_error_handler, BevyError, ErrorContext, Result},
     prelude::Resource,
     query::Access,
     schedule::{is_apply_deferred, BoxedCondition, ExecutorKind, SystemExecutor, SystemSchedule},
@@ -538,7 +538,7 @@ impl ExecutorState {
         world: UnsafeWorldCell,
     ) -> bool {
         let mut should_run = !self.skipped_systems.contains(system_index);
-        let error_handler = default_error_handler();
+        let error_handler = get_error_handler();
 
         for set_idx in conditions.sets_with_conditions_of_systems[system_index].ones() {
             if self.evaluated_sets.contains(set_idx) {
@@ -787,7 +787,7 @@ unsafe fn evaluate_and_fold_conditions(
     conditions: &mut [BoxedCondition],
     world: UnsafeWorldCell,
 ) -> bool {
-    let error_handler = default_error_handler();
+    let error_handler = get_error_handler();
 
     #[expect(
         clippy::unnecessary_fold,

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

@@ -8,7 +8,7 @@ use tracing::info_span;
 use std::eprintln;
 
 use crate::{
-    error::{default_error_handler, BevyError, ErrorContext},
+    error::{get_error_handler, BevyError, ErrorContext},
     schedule::{
         executor::is_apply_deferred, BoxedCondition, ExecutorKind, SystemExecutor, SystemSchedule,
     },
@@ -167,7 +167,7 @@ impl SimpleExecutor {
 }
 
 fn evaluate_and_fold_conditions(conditions: &mut [BoxedCondition], world: &mut World) -> bool {
-    let error_handler = default_error_handler();
+    let error_handler = get_error_handler();
 
     #[expect(
         clippy::unnecessary_fold,

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

@@ -8,7 +8,7 @@ use tracing::info_span;
 use std::eprintln;
 
 use crate::{
-    error::{default_error_handler, BevyError, ErrorContext},
+    error::{get_error_handler, BevyError, ErrorContext},
     schedule::{is_apply_deferred, BoxedCondition, ExecutorKind, SystemExecutor, SystemSchedule},
     world::World,
 };
@@ -211,7 +211,7 @@ impl SingleThreadedExecutor {
 }
 
 fn evaluate_and_fold_conditions(conditions: &mut [BoxedCondition], world: &mut World) -> bool {
-    let error_handler: fn(BevyError, ErrorContext) = default_error_handler();
+    let error_handler: fn(BevyError, ErrorContext) = get_error_handler();
 
     #[expect(
         clippy::unnecessary_fold,

crates/bevy_ecs/src/schedule/schedule.rs

@@ -27,7 +27,7 @@ use tracing::info_span;
 
 use crate::{
     component::{ComponentId, Components, Tick},
-    error::default_error_handler,
+    error::get_error_handler,
     prelude::Component,
     resource::Resource,
     schedule::*,
@@ -441,7 +441,7 @@ impl Schedule {
         self.initialize(world)
             .unwrap_or_else(|e| panic!("Error when initializing schedule {:?}: {e}", self.label));
 
-        let error_handler = default_error_handler();
+        let error_handler = get_error_handler();
 
         #[cfg(not(feature = "bevy_debug_stepping"))]
         self.executor

crates/bevy_ecs/src/system/commands/mod.rs

@@ -89,8 +89,8 @@ use crate::{
 /// A [`Command`] can return a [`Result`](crate::error::Result),
 /// which will be passed to an [error handler](crate::error) if the `Result` is an error.
 ///
-/// The [default error handler](crate::error::default_error_handler) panics.
-/// It can be configured by setting the `GLOBAL_ERROR_HANDLER`.
+/// The [default error handler](crate::error::get_error_handler) panics.
+/// It can be configured by using the [`set_error_handler`](crate::error::set_error_handler) method.
 ///
 /// Alternatively, you can customize the error handler for a specific command
 /// by calling [`Commands::queue_handled`].
@@ -509,7 +509,7 @@ impl<'w, 's> Commands<'w, 's> {
     /// Pushes a generic [`Command`] to the command queue.
     ///
     /// If the [`Command`] returns a [`Result`],
-    /// it will be handled using the [default error handler](crate::error::default_error_handler).
+    /// it will be handled using the [default error handler](crate::error::get_error_handler).
     ///
     /// To use a custom error handler, see [`Commands::queue_handled`].
     ///
@@ -695,7 +695,7 @@ impl<'w, 's> Commands<'w, 's> {
     /// This command will fail if any of the given entities do not exist.
     ///
     /// It will internally return a [`TryInsertBatchError`](crate::world::error::TryInsertBatchError),
-    /// which will be handled by the [default error handler](crate::error::default_error_handler).
+    /// which will be handled by the [default error handler](crate::error::get_error_handler).
     #[track_caller]
     pub fn insert_batch<I, B>(&mut self, batch: I)
     where
@@ -726,7 +726,7 @@ impl<'w, 's> Commands<'w, 's> {
     /// This command will fail if any of the given entities do not exist.
     ///
     /// It will internally return a [`TryInsertBatchError`](crate::world::error::TryInsertBatchError),
-    /// which will be handled by the [default error handler](crate::error::default_error_handler).
+    /// which will be handled by the [default error handler](crate::error::get_error_handler).
     #[track_caller]
     pub fn insert_batch_if_new<I, B>(&mut self, batch: I)
     where
@@ -1223,8 +1223,8 @@ impl<'w, 's> Commands<'w, 's> {
 /// An [`EntityCommand`] can return a [`Result`](crate::error::Result),
 /// which will be passed to an [error handler](crate::error) if the `Result` is an error.
 ///
-/// The [default error handler](crate::error::default_error_handler) panics.
-/// It can be configured by setting the `GLOBAL_ERROR_HANDLER`.
+/// The [default error handler](crate::error::get_error_handler) panics.
+/// It can be configured by using the [`set_error_handler`](crate::error::set_error_handler) method.
 ///
 /// Alternatively, you can customize the error handler for a specific command
 /// by calling [`EntityCommands::queue_handled`].
@@ -1767,7 +1767,7 @@ impl<'a> EntityCommands<'a> {
     /// Pushes an [`EntityCommand`] to the queue,
     /// which will get executed for the current [`Entity`].
     ///
-    /// The [default error handler](crate::error::default_error_handler)
+    /// The [default error handler](crate::error::get_error_handler)
     /// will be used to handle error cases.
     /// Every [`EntityCommand`] checks whether the entity exists at the time of execution
     /// and returns an error if it does not.

examples/ecs/error_handling.rs

@@ -5,7 +5,7 @@
 //! enabled. This feature is disabled by default, as it may introduce runtime overhead, especially for commands.
 
 use bevy::ecs::{
-    error::{warn, GLOBAL_ERROR_HANDLER},
+    error::{set_error_handler, warn},
     world::DeferredWorld,
 };
 use bevy::math::sampling::UniformMeshSampler;
@@ -22,9 +22,7 @@ fn main() {
     // Here we set the global error handler using one of the built-in
     // error handlers. Bevy provides built-in handlers for `panic`, `error`, `warn`, `info`,
     // `debug`, `trace` and `ignore`.
-    GLOBAL_ERROR_HANDLER
-        .set(warn)
-        .expect("The error handler can only be set once, globally.");
+    set_error_handler(warn);
 
     let mut app = App::new();