Error handling

An application fails in two places. A view is asked for something it cannot produce, or the application never starts at all. The two have different types, different recovery and different tools. This page assumes Control flow and Components.

A Result is a view

impl<V: View, E: Display + 'static> View for Result<V, E>

The bound on the error is Display + 'static and nothing else. It does not have to implement std::error::Error, and it does not have to be Send.

use zgui::prelude::*;

/// One reading, or the reason it could not be shown.
#[component]
fn Reading(line: Signal<String>) -> impl IntoView {
    view! {
        row(class = "reading") {
            {move || line.with(|line| parse(line)).map(|value| view! {
                text(class = "reading__value") {{format!("{value:.2}")}}
            })}
        }
    }
}

fn parse(line: &str) -> Result<f32, String> {
    line.trim()
        .parse::<f32>()
        .map_err(|error| format!("{line:?} is not a number: {error}"))
}

The closure is a reactive hole, so the parse runs again whenever line changes. What the two arms do:

On a rebuild, an Err first removes whatever the Ok arm had built, then reports. A view that starts failing does not leave the last good render on screen.

ViewError and report_error

pub struct ViewError(/* private */);        // Clone + Debug + Display

impl ViewError {
    pub fn new(message: impl Display) -> Self;
    pub fn message(&self) -> &str;
}

pub fn report_error(error: ViewError);

ViewError keeps the message and nothing else. It is deliberately thin: the view layer never inspects an error, it only carries it to a boundary that shows it or logs it.

ViewError and ErrorBoundary are in the prelude. report_error is not — write use zgui::view::report_error;.

Call report_error where a Result is not the shape you have:

use zgui::view::report_error;

#[component]
fn Panel(source: Signal<String>) -> impl IntoView {
    if let Err(error) = check(&source.get_untracked()) {
        report_error(ViewError::new(error));
    }
    view! { column(class = "panel") { /* … */ } }
}

Which boundary it finds

report_error looks the boundary up through the owner — the scope chain that disposes of state (see Context) — not through the element tree. Everything that runs under the scope it was written in reaches the right boundary.

For work on a task, write the failure into a signal and let a Result in the view report it. That also puts the report on the UI thread, which is where a boundary can be read at all.

ErrorBoundary

impl<C, F> ErrorBoundary<C, F>
where
    C: Fn() -> AnyView + 'static,
    F: Fn(&[ViewError]) -> AnyView + 'static,
{
    pub fn new(children: C, fallback: F) -> Self;
}

Children first, fallback second. Both produce an AnyView. The fallback is handed every error reported so far, in the order they arrived.

ErrorBoundary has no attribute spelling, because its arguments are not attributes. Write it as a value in a braced child, the same way Dynamic is written.

use zgui::prelude::*;

#[component]
fn Panel(line: Signal<String>) -> impl IntoView {
    view! {
        column(class = "panel") {
            label(class = "panel__title") {"Latest reading"}
            {ErrorBoundary::new(
                move || AnyView::new(view! { Reading(line = line) }),
                |errors: &[ViewError]| {
                    let messages: Vec<&str> = errors.iter().map(ViewError::message).collect();
                    AnyView::new(view! {
                        box(class = "panel__failure") {
                            label {"This reading could not be shown."}
                            text(class = "panel__why") {{messages.join("\n")}}
                        }
                    })
                },
            )}
        }
    }
}

What happens, in order:

The swap is not instant, and it does not need to be: a failing Result renders nothing from the moment it fails, so nothing wrong is on screen while the swap is pending. An error reported by the boundary's own child is swapped at the first flush after the report. An error reported from inside a nested conditional is swapped at the flush after that, because the conditional's own build is what runs at the first one.

Where a boundary does not catch

Recovering

A boundary latches. Nothing clears the error list, so once the fallback shows it shows for as long as that boundary exists. To try again, unmount the boundary and build a new one. A keyed list does exactly that when its key changes:

let attempt = RwSignal::new(0_u32);

view! {
    column(class = "panel") {
        // A new attempt number is a new key, so the old boundary goes and a new one — with an
        // empty error list — is built in its place.
        for id in move || [attempt.get()], key = |id: &u32| *id {
            {ErrorBoundary::new(
                move || AnyView::new(view! { Reading(line = line) }),
                move |errors: &[ViewError]| AnyView::new(view! {
                    column(class = "failure") {
                        label {{format!("Attempt {id} failed.")}}
                        text {{errors[0].message().to_owned()}}
                    }
                }),
            )}
        }
        control(class = "retry", on:click = move |_| attempt.update(|n| *n += 1)) {"Try again"}
    }
}

Rebuilding the same boundary in place — through Dynamic, or by letting a parent rebuild it — keeps the old error list, because the boundary reuses its state. The boundary has to be removed for the list to go.

Nesting boundaries

The nearest boundary above the failing view catches. An outer boundary never learns of an error an inner one took.

view! {
    // A backstop: it catches whatever the panels do not.
    {ErrorBoundary::new(
        || AnyView::new(view! {
            column(class = "app") {
                // Each panel fails on its own, and the rest of the window keeps working.
                {ErrorBoundary::new(left, panel_failure)}
                {ErrorBoundary::new(right, panel_failure)}
            }
        }),
        app_failure,
    )}
}

Put a boundary around each part of the interface that can fail without the rest failing, and one at the root. A window with only a root boundary answers any failure by replacing the whole interface.

Failing to start

fn main() -> Result<(), zgui::Error> {
    app()
        .with_title("Counter")
        .with_size(360.0, 300.0)
        .with_stylesheet(SHEET)
        .run(|| view! { Counter() })
}

zgui::Error is an alias for zgui_runtime::AppError. It is #[non_exhaustive], so a match on it needs a _ arm.

PlatformError is itself #[non_exhaustive], with four variants:

A failure found while the primary window opens happens after the platform backend has taken the application over. It is recorded, logged at error level under the tracing target zgui::app, and the loop is asked to exit; run then returns it. That is why run can report a failure that happened long after it was called.

If an additional window cannot open, the runtime logs the error, marks that window's handle closed, and keeps the other windows running. DocumentsExhausted prevents a stale node handle from ever resolving in a later window after all document identities have been used.

No graphics adapter

Error::GpuUnavailable carries every adapter that was considered and why each was rejected. There is no fallback: a window that opens and never paints looks like a program that has hung, so the framework reports the failure instead.

fn main() -> Result<(), zgui::Error> {
    let outcome = app().with_title("Counter").run(|| view! { Counter() });

    if let Err(zgui::Error::GpuUnavailable(ref failure)) = outcome {
        for adapter in &failure.candidates {
            eprintln!("rejected {}: {}", adapter.name, adapter.reason);
        }
    }
    outcome
}

candidates is a Vec<RejectedAdapter>, and each entry has a name and a reason, in the order they were tried.

No display server

Error::Platform(PlatformError::Backend(_)), carrying the windowing system's own message. The desktop backend builds its event loop first, and there is nothing to connect to — a session over SSH with no forwarded display is the usual cause. Nothing is opened and nothing is drawn.

A bad style sheet

Three different things, at three different times:

What panics

The framework catches no panic anywhere. An ErrorBoundary does not catch one, and a panic inside a reactive task reaches the frame loop that ran the flush. Every panic a call of yours can cause:

The messages are worth recognising:

provide_context requires a current owner: with none, the value it creates is
unreachable and never freed. Run it inside `Mounted::with`.

flush must run on the thread that installed the reactive runtime

Dereferenced SendWrapper<T> variable from a thread different to the one it has
been created with.

At src/main.rs:41:18, you tried to access a reactive value which was defined at
src/main.rs:12:21, but it has already been disposed.

What to do instead:

The debug-only rows are the important ones: they are checks, and in a release build they compile away. The call then does nothing at all, silently. Run the interface in a debug build at least once.

What fails silently

Most of these are visible only through tracing, so install a subscriber before the application runs:

fn main() -> Result<(), zgui::Error> {
    tracing_subscriber::fmt().init();
    assert!(zgui::reactive::effects_are_enabled());

    app().with_title("Counter").run(|| view! { Counter() })
}

The targets the framework logs under are zgui::app, zgui::css, zgui::style, zgui::input, zgui::observe, zgui::paint and zgui::platform.

"My interface does not update"

Next