Module error 

Error handling for Bevy systems, commands, and observers.

When a system is added to a Schedule, and its return type is that of Result, then Bevy considers those systems to be “fallible”, and the ECS scheduler will special-case the Err variant of the returned Result.

All BevyErrors returned by a system, observer or command are handled by an “error handler”. By default, the 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: Use DefaultErrorHandler to set a custom error handler function for a world, or App::set_error_handler for a whole 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.

Bevy provides a number of pre-built error-handlers for you to use:

• panic – panics with the system error
• error – logs the system error at the error level
• warn – logs the system error at the warn level
• info – logs the system error at the info level
• debug – logs the system error at the debug level
• trace – logs the system error at the trace level
• ignore – ignores the system error

However, you can use any custom error handler logic by providing your own function (or non-capturing closure that coerces to the function signature) as long as it matches the signature:

fn(BevyError, ErrorContext)

The ErrorContext allows you to access additional details relevant to providing context surrounding the error – such as the system’s name – in your error messages.

use bevy_ecs::error::{BevyError, ErrorContext, DefaultErrorHandler};
use log::trace;

fn my_error_handler(error: BevyError, ctx: ErrorContext) {
   if ctx.name().ends_with("plz_ignore") {
      trace!("Nothing to see here, move along.");
      return;
  }
  bevy_ecs::error::error(error, ctx);
}

fn main() {
    let mut world = World::new();
    world.insert_resource(DefaultErrorHandler(my_error_handler));
    // Use your world here
}

If you need special handling of individual fallible systems, you can use Bevy’s system piping feature to capture the Result output of the system and handle it accordingly.

When working with commands, you can handle the result of each command separately using the HandleError::handle_error_with method.

Structs

BevyError

The built in “universal” Bevy error type. This has a blanket From impl for any type that implements Rust’s Error, meaning it can be used as a “catch all” error.

DefaultErrorHandler

Error handler to call when an error is not handled otherwise. Defaults to panic().

Enums

ErrorContext

Context for a BevyError to aid in debugging.

Traits

CommandWithEntity

Passes in a specific entity to an EntityCommand, resulting in a Command that internally runs the EntityCommand on that entity.

HandleError

Takes a Command that potentially 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 ().

Functions

bevy_error_panic_hook

When called, this will skip the currently configured panic hook when a BevyError backtrace has already been printed.

debug

Error handler that logs the system error at the debug level.

error

Error handler that logs the system error at the error level.

ignore

Error handler that ignores the system error.

info

Error handler that logs the system error at the info level.

panic

Error handler that panics with the system error.

trace

Error handler that logs the system error at the trace level.

warn

Error handler that logs the system error at the warn level.

Type Aliases

ErrorHandler

Defines how Bevy reacts to errors.

Result

A result type for use in fallible systems, commands and observers.