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. Modify the [GLOBAL_ERROR_HANDLER] value 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.

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.

Remember to turn on the configurable_error_handler feature to set a global error handler!

use bevy_ecs::error::{GLOBAL_ERROR_HANDLER, BevyError, ErrorContext};
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() {
    // 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.");
     
    // Initialize your Bevy App 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.

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 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.
• default_error_handler
  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.
• 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

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