Add `new` and severity based constructors to `BevyError` by loreball · Pull Request #23684 · bevyengine/bevy

loreball · 2026-04-06T14:10:59Z

Objective

Add constructors for making BevyErrors with a specific severity. Closes #23676.

Solution

Add a new constructor plus 1 constructor for every possible Severity.

Testing

My eyes and a simple test case that constructs an error and tests if the downcasting works.

Showcase

A BevyError now has multiple constructor to create one with an expected severity

use bevy::ecs::error::{BevyError, Severity};

let debug_error = BevyError::new(Severity::Debug, "This works with strings");

let warn_error = BevyError::warn("There's a constructor for each severity level");

alice-i-cecile · 2026-04-06T17:11:21Z

crates/bevy_ecs/src/error/bevy_error.rs

 impl BevyError {
+    /// Creates a new [`BevyError`] with the given [severity](Severity).
+    pub fn new<E: Error + Sync + Send + 'static>(severity: Severity, error: E) -> Self {
+        Self::from(error).with_severity(severity)


Slightly simpler than my solution 🤔

crates/bevy_ecs/src/error/bevy_error.rs

alice-i-cecile · 2026-04-06T17:14:13Z

crates/bevy_ecs/src/error/bevy_error.rs

+
+    /// Creates a new [`BevyError`] from a printable error message.
+    ///
+    /// Prefer using other constructors if possible.


This guidance isn't great. When would you do this? Why should you prefer other constructors?

alice-i-cecile · 2026-04-06T17:14:34Z

crates/bevy_ecs/src/error/bevy_error.rs

+        Self::new(severity, error)
+    }
+
+    /// Checks if we're holding the internal error.


alice-i-cecile · 2026-04-06T17:15:09Z

crates/bevy_ecs/src/error/bevy_error.rs

+    /// Prefer using other constructors if possible.
+    pub fn msg<M: Display + Debug + Send + Sync + 'static>(severity: Severity, message: M) -> Self {
+        // TODO: We've already crossed the simple to complex function threshold by implementing a whole new type.
+        //       Consider downcasting to Box<dyn Error> to prevent double boxing.


I think we should do this :)

I tried it and it doesn't work cleanly. The problem is that we want to downcast the type into itself but dyn Any only allows downcasting to references. The only two ways to do this are either box the value and downcast that or to check if the type is the same using Any::is and then transmute. The first option allocates; the second one uses unsafe code. This is supposed to be a simple optimization.

I've removed the comment for now. The eventual switch to using vtables should obviate the issue.

crates/bevy_ecs/src/error/bevy_error.rs

alice-i-cecile · 2026-04-06T17:15:35Z

crates/bevy_ecs/src/error/bevy_error.rs

+/// A helper struct for constructing errors in [`BevyError::msg`].
+///
+/// We special case error downcasting to get to it's content when necessary.
+/// Never expose to the user.


Probably not needed.

alice-i-cecile · 2026-04-06T17:16:18Z

crates/bevy_ecs/src/error/bevy_error.rs


+/// Creates a new [`BevyError`] from a string.
+///
+/// Allows formatting the string like [`format!`](std::format!) and also take an optional severity argument.


This needs to be explicit that the severity argument comes first.

crates/bevy_ecs/src/error/bevy_error.rs

alice-i-cecile · 2026-04-06T17:18:06Z

crates/bevy_ecs/src/error/bevy_error.rs

+    }
+
+    #[test]
+    /// Testing the macros


Not helpful lol

alice-i-cecile · 2026-04-06T17:18:51Z

crates/bevy_ecs/src/error/bevy_error.rs

+
+/// Returns early with an error.
+///
+/// Equivalent to <code>return Err([bevy_error!(\...)](bevy_error!))</code>


This needs to mention the default error severity here too.

github-actions · 2026-04-06T17:19:18Z

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

alice-i-cecile · 2026-04-06T17:19:20Z

I really like this, but we should incorporate this into the error handling release note and get it in for 0.19.

chescock · 2026-04-06T17:43:58Z

crates/bevy_ecs/src/error/bevy_error.rs


 impl BevyError {
+    /// Creates a new [`BevyError`] with the given [severity](Severity).
+    pub fn new<E: Error + Sync + Send + 'static>(severity: Severity, error: E) -> Self {


You can use the same trick as the From impl to let this accept &'static str and String in addition to other errors:

Suggested change

pub fn new<E: Error + Sync + Send + 'static>(severity: Severity, error: E) -> Self {

pub fn new<E>(severity: Severity, error: E) -> Self

where

Box<dyn Error + Sync + Send>: From<E>,

{

That would also supersede from_boxed, since it would use the identity From impl (and not double-box!).

Accepting both &str and impl Error requires unstable language features because they could theoretically overlap, but the standard library cheats and uses them in the implementation of Error, which we can take advantage of using that bound.

Yep, this is what I did in my impl :)

Also makes from_boxed unnecessary since From is reflexive.

chescock · 2026-04-06T17:45:22Z

crates/bevy_ecs/src/error/bevy_error.rs

+    /// Creates a new [`BevyError`] from a printable error message.
+    ///
+    /// Prefer using other constructors if possible.
+    pub fn msg<M: Display + Debug + Send + Sync + 'static>(severity: Severity, message: M) -> Self {


Is msg mainly intended to support the macro? format! returns a String, so if you restrict this to only take String then you can get rid of DisplayError and just use Self::from(error).

And if you generalize new, then you can get rid of this method entirely in favor of the macro calling new.

At first it only supported strings for the macro. Then I looked at eyre and anyhow saw the method and stole it. I don't think we need it for now. I'll switch to using new.

alice-i-cecile · 2026-04-06T18:51:29Z

crates/bevy_ecs/src/error/bevy_error.rs

+/// }
+/// ```
+#[macro_export]
+macro_rules! bevy_error {


IMO the core benefit over BevyError::new is the formatting. The docs should make that clearer.

SpecificProtagonist · 2026-04-06T18:53:44Z

crates/bevy_ecs/src/error/bevy_error.rs

+    };
+    // Doing the severity things means rustfmt can't format it but sadly it's the only way to make it work
+    (severity: $severity:expr, $($args:tt)+) => {
+        $crate::error::BevyError::msg($severity, std::format!($($args)*))


Suggested change

$crate::error::BevyError::msg($severity, std::format!($($args)*))

$crate::error::BevyError::msg($severity, ::alloc::format!($($args)*))

SpecificProtagonist · 2026-04-06T18:56:14Z

crates/bevy_ecs/src/error/bevy_error.rs

+    (severity: $severity:expr) => {
+        compile_error!("missing error message")
+    };
+    // Doing the severity things means rustfmt can't format it but sadly it's the only way to make it work


Since the format string is a literal and the severity isn't, we can check for that:

macro_rules! bevy_error { ($fmt:literal $(, $arg:tt)*) => { $crate::error::BevyError::new(::alloc::format!($fmt $(, $arg)*), $crate::error::Severity::Panic) }; ($severity:expr, $($arg:tt)*) => { $crate::error::BevyError::new(::alloc::format!($($arg)*), $severity) }; ($severity:expr) => { compile_error!("missing error message") }; }

Note that requiring the format string to be a literal means it can't be a variable etc.

Note that requiring the format string to be a literal means it can't be a variable etc.

That's already the case with format!.

benfrankel · 2026-04-06T19:03:10Z

Maybe instead of a separate bevy_error! macro to support format!-style arguments, we could provide shorthand methods on BevyError for constructing a new error with a severity level and recommend format! in the documentation? For example:

return bevy_error!(severity: Severity::Debug, "Not exactly one player: {:?}", error);
return BevyError::debug(format!("Not exactly one player: {:?}", error));

This would be a bit shorter and work better with IDEs (suggestions on BevyError::, and rustfmt would work).

alice-i-cecile · 2026-04-06T19:07:19Z

Maybe instead of a separate bevy_error! macro to support format!-style arguments, we could provide shorthand methods on BevyError for constructing a new error with a severity level and recommend format! in the documentation? For example:

I think we should do this, regardless of our decision on the bevy_error! macro.

ChristopherBiscardi · 2026-04-06T21:02:05Z

Worth noting that miette covers this design space already, including severity and other additions, as well as followup functions on the error: https://docs.rs/miette/7.6.0/miette/macro.miette.html

use miette::{miette, LabeledSpan, Severity};

let source = "(2 + 2".to_string();
let report = miette!(
    // Those fields are optional
    severity = Severity::Error,
    code = "expected::rparen",
    help = "always close your parens",
    labels = vec![LabeledSpan::at_offset(6, "here")],
    url = "https://example.com",
    // Rest of the arguments are passed to `format!`
    // to form diagnostic message
    "expected closing ')'"
)
.with_source_code(source);

dsgallups

Really like the idea! I think that this macro is straightforward and approachable. I struggle to see how this could convolute things. Big fan.

dsgallups · 2026-04-07T18:51:08Z

crates/bevy_ecs/src/error/bevy_error.rs

+    ($fmt:literal) => {
+        $crate::error::BevyError::new($crate::error::Severity::Panic, $fmt)
+    };
+    ($fmt:literal, $($arg:tt)*) => {
+        $crate::error::BevyError::new($crate::error::Severity::Panic, ::alloc::format!($fmt, $($arg)*))
+    };


suggestion: panicking by default continues to be unexpected behavior. If the severity here directly leads to a panic, then I can see users getting upset. At least, I'd get upset.

Nonetheless, this appears to be the behavior now for bevy, so this suggestion might be OOS, and met in a different issue regarding default error handling.

alice-i-cecile

Let's cut the macros from this PR to reduce controversy. The rest of this is really good, and I don't want to see it blocked.

Feel free to open a new PR for just the macros afterwards, and we can discuss the merits of them there.

Some more ways to construct a BevyError. Used for example in the upcoming macro

We set RUST_BACKTRACE in infiltered_backtrace_test to force backtrace printing. But the state of the variable is cached so if any previous test leads to the creation of a backtrace the variable gets cached as unset and backtraces get disabled. This breaks the test. The solution is to stop changing env variables in tests and instead to do it in the ci test harness. The test itself has been modified to check the env state and to fail if it's invalid

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

loreball · 2026-04-07T20:36:08Z

Well, it's done. Can't change the branch name without opening a new pr but everything else has been updated. I'll open a pr for the macros if/when this gets merged so I'm not constantly rebasing the pr on top of this one.

benfrankel

Leaving some optional documentation nits, otherwise looks good to me.

benfrankel · 2026-04-07T20:38:27Z

crates/bevy_ecs/src/error/bevy_error.rs

 impl BevyError {
+    /// Constructs a new [`BevyError`] with the given [`Severity`].
+    ///
+    /// The stored error will be stored as a `Box<dyn Error + Send + Sync>`.


Suggested change

/// The stored error will be stored as a `Box<dyn Error + Send + Sync>`.

/// The error will be stored as a `Box<dyn Error + Send + Sync>`.

Nit

benfrankel · 2026-04-07T20:39:16Z

crates/bevy_ecs/src/error/bevy_error.rs

+    ///
+    /// The stored error will be stored as a `Box<dyn Error + Send + Sync>`.
+    ///
+    /// The easiest way to use this is to simply pass in a quoted bit of text.


Suggested change

/// The easiest way to use this is to simply pass in a quoted bit of text.

/// The easiest way to use this is to pass in a string.

Nit

benfrankel · 2026-04-07T20:42:14Z

crates/bevy_ecs/src/error/bevy_error.rs

+    /// Create a new [`BevyError`] with the [`Severity::Ignore`] severity
+    ///
+    /// This is a shorthand for <code>[BevyError::new(Severity::Ignore, error)](BevyError::new)</code>


Suggested change

/// Create a new [`BevyError`] with the [`Severity::Ignore`] severity

///

/// This is a shorthand for <code>[BevyError::new(Severity::Ignore, error)](BevyError::new)</code>

/// Creates a new [`BevyError`] with the [`Severity::Ignore`] severity.

///

/// This is a shorthand for <code>[BevyError::new(Severity::Ignore, error)](BevyError::new)</code>.

Nit

Same comment for the other shorthand constructors.

benfrankel · 2026-04-07T20:43:54Z

crates/bevy_ecs/src/error/bevy_error.rs

+        Self::new(Severity::Panic, error)
+    }
+
+    /// Checks if we're holding the internal error.


Suggested change

/// Checks if we're holding the internal error.

/// Checks if the internal error is of type `E`.

Nit

Alternatively, "Checks if the internal error is of the given type."

loreball changed the title ~~Bevy error macros~~ Add bevy_error macro Apr 6, 2026

loreball force-pushed the bevy_error_macros branch 5 times, most recently from 4224b5a to 1edb7f9 Compare April 6, 2026 16:52

alice-i-cecile mentioned this pull request Apr 6, 2026

Add BevyError::new to explicitly construct a BevyError with a Severity #23690

Closed

github-project-automation bot added this to ECS Apr 6, 2026

github-project-automation bot moved this to Needs SME Triage in ECS Apr 6, 2026

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

crates/bevy_ecs/src/error/bevy_error.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

crates/bevy_ecs/src/error/bevy_error.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

crates/bevy_ecs/src/error/bevy_error.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

crates/bevy_ecs/src/error/bevy_error.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

crates/bevy_ecs/src/error/bevy_error.rs Outdated

}

#[test]

/// Testing the macros

Copy link
Copy Markdown

Member

alice-i-cecile Apr 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not helpful lol

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

alice-i-cecile added the M-Release-Note Work that should be called out in the blog due to impact label Apr 6, 2026

alice-i-cecile added this to the 0.19 milestone Apr 6, 2026

alice-i-cecile changed the title ~~Add bevy_error macro~~ Add bevy_error! and bail!` macros, along with other small helpers Apr 6, 2026

alice-i-cecile changed the title ~~Add bevy_error! and bail!` macros, along with other small helpers~~ Add bevy_error! and bail! macros, along with other small helpers Apr 6, 2026

alice-i-cecile added the D-Modest A "normal" level of difficulty; suitable for simple features or challenging fixes label Apr 6, 2026

chescock reviewed Apr 6, 2026

View reviewed changes

loreball force-pushed the bevy_error_macros branch from 5f7a242 to 4f79e79 Compare April 6, 2026 18:32

alice-i-cecile reviewed Apr 6, 2026

View reviewed changes

SpecificProtagonist reviewed Apr 6, 2026

View reviewed changes

loreball force-pushed the bevy_error_macros branch from f36730d to c88869b Compare April 7, 2026 16:27

dsgallups approved these changes Apr 7, 2026

View reviewed changes

alice-i-cecile requested changes Apr 7, 2026

View reviewed changes

loreball and others added 5 commits April 7, 2026 21:44

Add BevyError::new

bcae0a9

Add helpers to BevyError

fa1ef76

Some more ways to construct a BevyError. Used for example in the upcoming macro

Fix BevyError::new documentation

65e1337

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

Change bounds for BevyError::new to allow the direct use of strings

9c50aca

loreball force-pushed the bevy_error_macros branch from c88869b to 9ec8180 Compare April 7, 2026 19:59

loreball changed the title ~~Add bevy_error! and bail! macros, along with other small helpers~~ Add new and severity based constructors to BevyError Apr 7, 2026

Add severity based constructors to BevyError

c923d8e

loreball force-pushed the bevy_error_macros branch from 9ec8180 to c923d8e Compare April 7, 2026 20:06

benfrankel approved these changes Apr 7, 2026

View reviewed changes

Fix some typos

09a0596

-    pub fn new<E: Error + Sync + Send + 'static>(severity: Severity, error: E) -> Self {
+    pub fn new<E>(severity: Severity, error: E) -> Self
+    where
+        Box<dyn Error + Sync + Send>: From<E>,
+    {

	$crate::error::BevyError::msg($severity, std::format!($($args)*))
	$crate::error::BevyError::msg($severity, ::alloc::format!($($args)*))

	/// The stored error will be stored as a `Box<dyn Error + Send + Sync>`.
	/// The error will be stored as a `Box<dyn Error + Send + Sync>`.

	/// The easiest way to use this is to simply pass in a quoted bit of text.
	/// The easiest way to use this is to pass in a string.

	/// Checks if we're holding the internal error.
	/// Checks if the internal error is of type `E`.

Uh oh!

Conversation

loreball commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Showcase

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 6, 2026

Uh oh!

alice-i-cecile commented Apr 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

loreball Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

loreball Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SpecificProtagonist Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benfrankel commented Apr 6, 2026

Uh oh!

alice-i-cecile commented Apr 6, 2026

Uh oh!

ChristopherBiscardi commented Apr 6, 2026

Uh oh!

dsgallups left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile left a comment

Choose a reason for hiding this comment

Uh oh!

loreball commented Apr 7, 2026

Uh oh!

benfrankel left a comment

Choose a reason for hiding this comment

Uh oh!

loreball commented Apr 6, 2026 •

edited

Loading

loreball Apr 6, 2026 •

edited

Loading

loreball Apr 6, 2026 •

edited

Loading

SpecificProtagonist Apr 6, 2026 •

edited

Loading