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 match_severity error handler function is used, which defers to an error’s Severity.

You can change the default behavior by registering a custom error handler: Use FallbackErrorHandler 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:

• match_severity defers to an error’s Severity, using one of the handlers listed below.
• 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, FallbackErrorHandler};
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(FallbackErrorHandler(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 Command::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.

FallbackErrorHandler

Fallback error handler to call when an error is not handled otherwise. Defaults to match_severity().

Enums

ErrorContext

Context for a BevyError to aid in debugging.

Severity

Indicates how severe a BevyError is.

Traits

CommandOutput

A trait implemented for types that can be used as the output of a Command.

EntityCommandOutput

A trait implemented for types that can be used as the output of an EntityCommand.

ResultSeverityExt

Extension methods for annotating errors with a Severity.

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.

match_severity

Error handler that defers to an error’s Severity.

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

DefaultErrorHandlerDeprecated

Deprecated alias for FallbackErrorHandler.

ErrorHandler

Defines how Bevy reacts to errors.

Result

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