Enum WslError 

pub enum WslError {
    UnsupportedPlatform {
        operation: &'static str,
    },
    Spawn {
        program: PathBuf,
        source: Error,
    },
    ChildControl {
        program: PathBuf,
        source: Error,
    },
    SecretInCommandLine {
        program: PathBuf,
        location: String,
    },
    CommandFailed {
        what: &'static str,
        program: PathBuf,
        exit_code: Option<i32>,
        detail: String,
    },
    InvalidName {
        requested: String,
        reason: String,
    },
    NotInstalled {
        requested: String,
        available: Vec<String>,
    },
    AmbiguousName {
        requested: String,
    },
    NotWsl2 {
        distribution: String,
        version: u8,
    },
    NoRootAccess {
        distribution: String,
        detail: String,
    },
    UnsupportedArchitecture {
        distribution: String,
        reported: String,
    },
    SystemdUnavailable {
        distribution: String,
        detail: String,
    },
    UnreadableChecksums {
        detail: String,
    },
    NoSuchArtifact {
        version: String,
        triple: String,
        published: usize,
    },
    AmbiguousArtifact {
        version: String,
        triple: String,
        count: usize,
    },
    UnreadableArchive {
        path: PathBuf,
        detail: String,
    },
    DigestMismatch {
        path: PathBuf,
        expected: String,
        actual: String,
    },
    InvalidDestination {
        path: String,
        reason: String,
    },
    VersionMismatch {
        expected: String,
        reported: String,
    },
    ForeignTask {
        name: String,
        detail: String,
    },
    NoSuchTask {
        name: String,
    },
    TaskControl {
        operation: &'static str,
        name: String,
        detail: String,
    },
    NeedsElevation {
        operation: &'static str,
        name: String,
        detail: String,
    },
    Record {
        operation: &'static str,
        path: PathBuf,
        detail: String,
    },
    RecordSchema {
        path: PathBuf,
        found: u32,
        supported: u32,
    },
}

Anything that can go wrong managing a WSL distribution.

One enum rather than one per module: every variant here is something an operator reads on their own terminal, and a chain of From conversions between six error types would add wrapping without adding a single fact. The variants are ordered as the work is: platform, process, discovery, preflight, artifact, task, record.

Variants

UnsupportedPlatform

This build is not for Windows, so there is no WSL to manage.

Fields

operation: &'static str

What the caller was trying to do.

Spawn

The program could not be launched at all.

Fields

program: PathBuf

The program that could not be launched.

source: Error

The underlying error.

ChildControl

Waiting on or killing a child failed.

Fields

program: PathBuf

The program that could not be waited on.

source: Error

The underlying error.

SecretInCommandLine

The stdin payload was about to be visible in a process listing.

Deliberately does not quote the payload: an error message is one of the places 03-security-and-lifecycle.md says it must not appear.

Fields

program: PathBuf

The program that would have been launched.

location: String

Where the payload was found.

CommandFailed

A program ran and refused.

Fields

what: &'static str

What was being attempted.

program: PathBuf

The program that refused.

exit_code: Option<i32>

Its exit code, when it had one.

detail: String

What it said.

InvalidName

The distribution name cannot be used at all.

Fields

requested: String

What was asked for.

reason: String

Which rule it broke.

NotInstalled

No distribution of that name is installed.

Fields

requested: String

What was asked for.

available: Vec<String>

What is really there.

AmbiguousName

Two rows carry the name, so there is nothing safe to act on.

Fields

requested: String

The name that appeared twice.

NotWsl2

The distribution is not WSL2.

Fields

distribution: String

The distribution.

version: u8

The version WSL reported.

NoRootAccess

The distribution does not start as root.

Fields

distribution: String

The distribution.

detail: String

What id -u said.

UnsupportedArchitecture

The distribution’s architecture has no published artifact.

Fields

distribution: String

The distribution.

reported: String

What uname -m said.

SystemdUnavailable

systemd is not running the distribution.

Fields

distribution: String

The distribution.

detail: String

What systemctl said.

UnreadableChecksums

The checksum document could not be read.

Fields

detail: String

Why not.

NoSuchArtifact

The release publishes nothing for this version and architecture.

Fields

version: String

The version that was asked for.

triple: String

The target triple that was asked for.

published: usize

How many assets the document did list.

AmbiguousArtifact

The release publishes more than one archive for this target.

Fields

version: String

The version that was asked for.

triple: String

The target triple.

count: usize

How many matched.

UnreadableArchive

The archive on disk could not be read.

Fields

path: PathBuf

The archive.

detail: String

Why not.

DigestMismatch

The archive is not the one that was published.

Fields

path: PathBuf

The archive.

expected: String

What the release published.

actual: String

What it really hashes to.

InvalidDestination

The destination path cannot be installed to.

Fields

path: String

What was asked for.

reason: String

Which rule it broke.

VersionMismatch

The unpacked binary is not the version that was selected.

Fields

expected: String

The version that was selected.

reported: String

What the binary said about itself.

ForeignTask

A task of the product’s name exists and is somebody else’s.

Fields

name: String

The task name.

detail: String

Why it was judged foreign, and what to do.

NoSuchTask

There is no such task registered.

Fields

name: String

The task name.

TaskControl

Task Scheduler refused.

Fields

operation: &'static str

What was being attempted.

name: String

The task name.

detail: String

What schtasks said.

NeedsElevation

Task Scheduler refused for want of privilege.

Fields

operation: &'static str

What was being attempted.

name: String

The task name.

detail: String

What schtasks said.

Record

A provider record could not be read or written.

Fields

operation: &'static str

What was being attempted.

path: PathBuf

The record.

detail: String

Why not.

RecordSchema

A provider record was written by a version this one does not know.

Fields

path: PathBuf

The record.

found: u32

The version in the file.

supported: u32

The version this build writes.

Implementations

impl WslError

pub fn kind(&self) -> &'static str

A short, stable token for a status document or a log field.

Stable across message rewordings, which the prose above is not.

pub fn is_preflight(&self) -> bool

Whether this failure happened before anything was changed.

The column 03-security-and-lifecycle.md’s failure table is really about: an operator wants to know whether to clean something up before rerunning, and for every variant here the answer is “no” — the mutating steps report Self::CommandFailed, Self::TaskControl or Self::Record, and each of those is documented at its call site with what it left behind.

Trait Implementations

impl Debug for WslError

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

Formats the value using the given formatter.

impl Display for WslError

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

Formats the value using the given formatter.

impl Error for WslError

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.