NEOLearn

Error handling

Return Result from systems, observers and commands, use the ? operator, set error severity, and choose what the app does with errors through error handlers.

Updated October 20, 2026

On this page

Systems, observers and commands can fail: a resource isn't there yet, an entity was despawned, a mesh can't be built. Instead of unwrap, a system can return Result and use ?. The engine passes any error to an error handler, which decides whether to panic, log it or ignore it.

Fallible systems#

Return Result (the engine's alias for Result<(), NeoError>, in the prelude):

Rust
use neo::prelude::*;

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) -> Result {
    let mut sphere = Sphere::new(1.0).mesh().ico(7)?; // fails for too many subdivisions
    sphere.generate_tangents()?;

    commands.spawn((
        Mesh3d(meshes.add(sphere)),
        MeshMaterial3d(materials.add(StandardMaterial::default())),
    ));
    Ok(())
}

NeoError converts from any error type and from &str, so ? works on most things, and option.ok_or("message")? turns a missing value into an error. Observers can return Result the same way, and so can commands.

Severity#

Every error carries a Severity, which the default handler uses to decide what to do. Errors are Severity::Panic unless you say otherwise.

SeverityThe default handler
IgnoreDoes nothing.
Trace, Debug, InfoLogs at that level.
WarningLogs a warning.
ErrorLogs an error and carries on.
PanicPanics.

Set it where the error happens:

Rust
fn read_settings(world: &mut World) -> Result {
    world
        .get_resource::<Settings>()
        .ok_or("settings not loaded yet")
        .with_severity(Severity::Debug)?; // expected during loading: don't panic
    Ok(())
}

#[derive(Resource)]
struct Settings;

map_severity(|e| ..) picks a severity from the error value.

Error handlers#

The handler applies to every system, observer and command in the app that doesn't handle its own errors. The default, match_severity, follows each error's severity. Replace it for the whole app:

Rust
use neo::ecs::error::warn;

fn main() {
    App::new()
        .set_error_handler(warn) // log every unhandled error as a warning
        .add_plugins(DefaultPlugins)
        .run();
}

Built-in handlers, in neo::ecs::error: match_severity, panic, error, warn, info, debug, trace and ignore. A handler is any fn(NeoError, ErrorContext); the ErrorContext names the system, observer or command that failed:

Rust
use neo::ecs::error::{ErrorContext, NeoError};

fn my_handler(error: NeoError, context: ErrorContext) {
    if context.name().ends_with("optional_effects") {
        return; // never mind
    }
    neo::ecs::error::error(error, context);
}

Missing system parameters#

When a system's parameters can't be fetched, for example a Res<T> whose resource doesn't exist, that's an error too, and it goes to the same handler. Parameters such as Single, Populated and If skip the system instead; see System parameters.

Handling one system's errors yourself#

Pipe the system's result into another system to handle it there instead of in the global handler:

Rust
app.add_systems(
    Update,
    setup_level.pipe(|In(result): In<Result>| {
        if let Err(error) = result {
            warn!("level setup failed: {error}");
        }
    }),
);

For commands, commands.queue_handled(command, handler) gives one command its own handler, and the try_ command variants (try_insert, try_despawn) do nothing when the entity is gone.

Examples#

Run these from the engine core's workspace:

ExampleWhat it shows
cargo run --example error_handlingFallible systems, observers and commands, severities and a custom handler.
cargo run --example fallible_paramsParameters that skip a system instead of failing.

Next steps#