Enum ShellError 

#[non_exhaustive]
pub enum ShellError {
    NoBackend {
        tried: String,
    },
    UnknownBackend {
        requested: String,
        available: String,
    },
    Connect {
        backend: ShellBackend,
        detail: String,
    },
    Disconnected {
        backend: ShellBackend,
        detail: String,
    },
    InvalidWindow {
        bits: u64,
    },
    NoSuchMonitor(u32),
    WindowCreation(String),
    InvalidDescriptor(String),
    NoPendingCloseRequest {
        window: WindowId,
    },
    Unsupported {
        backend: ShellBackend,
        what: &'static str,
    },
    Backend(String),
    NeedsUserInteraction {
        backend: ShellBackend,
        what: &'static str,
    },
}

A shell operation failed.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NoBackend

No backend could be opened.

tried lists the backends that were attempted in order, so the log line distinguishes “there is no WAYLAND_DISPLAY and no DISPLAY” from “the Wayland backend is not compiled into this build”. See open.

Fields

tried: String

Comma-separated backend names, in the order they were attempted.

UnknownBackend

CRCBL_SHELL named a backend this build does not have.

A hard error rather than a fallback: someone who set the variable wanted that backend, and silently running on a different one turns a debugging session into a wild goose chase.

Fields

requested: String

The value of CRCBL_SHELL.

available: String

Comma-separated names of the backends that are compiled in.

Connect

Connecting to the window system failed — no compositor socket, a refused X11 connection, a browser with no canvas.

Fields

backend: ShellBackend

Backend that failed to connect.

detail: String

What went wrong, verbatim from the backend.

Disconnected

The connection to the window system was lost mid-session. Nothing the shell owns is usable afterwards.

Distinct from ShellError::Connect because the recovery differs: a failed connect is a startup problem a user can fix, and a lost connection means the compositor died or the session ended, which is a clean-shutdown signal.

Fields

backend: ShellBackend

Backend whose connection dropped.

detail: String

What the backend reported.

InvalidWindow

A WindowId did not resolve: it was destroyed, never created, or came from a different shell.

The generational Handle behind WindowId makes this a clean failure rather than an operation applied to whatever window took the slot — the same argument as crcbl-hal’s InvalidHandle.

Fields

bits: u64

The handle’s packed bits, from Handle::to_bits.

NoSuchMonitor(u32)

A MonitorId named a monitor that is not connected — usually one that was unplugged between monitors and the call that used its id.

WindowCreation(String)

Creating the window failed.

InvalidDescriptor(String)

A descriptor field was out of range or self-inconsistent — a caller bug, which is why the message is expected to name the field.

NoPendingCloseRequest

The reply named a window with no close request outstanding.

An error rather than a no-op because it is always a state-machine bug in the caller: the reply either arrived twice or was addressed to the wrong window, and both silently leave a real close request unanswered.

Fields

window: WindowId

The window the reply named.

Unsupported

The operation is real but this backend cannot do it.

Always paired with a ShellCaps flag: a caller that checks caps first never sees this, and a caller that does not gets an error naming the capability it should have checked. Getting this back is the signal that a consumer is missing a caps branch — which is exactly the platform-sniffing regression ShellCaps exists to prevent.

Fields

backend: ShellBackend

Backend that refused.

what: &'static str

What was asked for.

Backend(String)

Anything else the backend wants to report verbatim.

NeedsUserInteraction

The window system requires a recent user interaction for this, and there has not been one.

Why this is a named case rather than a backend string

It is a policy, not a fault, and the policy is the same one on three platforms:

• Wayland’s wl_data_device.set_selection quotes the serial of the input event that caused the copy, and a compositor checks it. A client that has received no input on a seat cannot take the clipboard.
• A browser gates navigator.clipboard.write() and Pointer Lock behind a user gesture, with the same reasoning and the same failure.
• X11 has no such requirement at all, and neither does Win32.

What it prevents is a background process silently taking the clipboard — so a caller must treat it as “ask the user to do that again”, never as a bug to work around. A backend on a platform without the rule never returns this, and that is obviously correct rather than obviously incomplete.

Fields

backend: ShellBackend

Which backend refused.

what: &'static str

What was being attempted, for the log line.

Implementations

impl ShellError

pub fn invalid_window(window: WindowId) -> Self

Builds a ShellError::InvalidWindow from a window handle.

Backends call this from their handle-lookup path so the error carries the same bits that appear in WindowId’s Debug output.

pub fn is_fatal(&self) -> bool

Whether the error means the window system is gone and the process should shut down rather than retry.

Trait Implementations

impl Debug for ShellError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ShellError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for ShellError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.