Enum AgentError 

pub enum AgentError {
    NotFound {
        container: String,
        reason: String,
    },
    PullFailed {
        image: String,
        reason: String,
    },
    CreateFailed {
        id: String,
        reason: String,
    },
    StartFailed {
        id: String,
        reason: String,
    },
    UnexpectedExit {
        id: String,
        code: i32,
    },
    HealthCheckFailed {
        id: String,
        reason: String,
    },
    InitActionFailed {
        id: String,
        reason: String,
    },
    Timeout {
        timeout: Duration,
    },
    DependencyTimeout {
        service: String,
        dependency: String,
        condition: String,
        timeout: Duration,
    },
    InvalidSpec(String),
    Network(String),
    Configuration(String),
    Internal(String),
    Unsupported(String),
    WslGpuUnavailable {
        reason: String,
    },
    GpuSharingUnavailable {
        mode: String,
        reason: String,
    },
    RouteToPeer {
        service: String,
        required_os: String,
        reason: String,
    },
    WrongPlatform {
        runtime: String,
        expected: String,
        actual: String,
        image: String,
    },
}

Agent runtime errors

Variants

NotFound

Container not found

Fields

container: String

reason: String

PullFailed

Failed to pull image

Fields

image: String

reason: String

CreateFailed

Failed to create container

Fields

id: String

reason: String

StartFailed

Failed to start container

Fields

id: String

reason: String

UnexpectedExit

Container exited unexpectedly

Fields

id: String

code: i32

HealthCheckFailed

Health check failed

Fields

id: String

reason: String

InitActionFailed

Init action failed

Fields

id: String

reason: String

Timeout

Timeout

Fields

timeout: Duration

DependencyTimeout

Dependency timeout - service waiting for dependency condition

Fields

service: String

dependency: String

condition: String

timeout: Duration

InvalidSpec(String)

Invalid spec

Network(String)

Network setup or operation failed

Configuration(String)

Configuration error (missing or invalid configuration)

Internal(String)

Internal runtime error

Unsupported(String)

Operation is not supported by this runtime

WslGpuUnavailable

GPU was requested by the service spec, but the underlying WSL2 host cannot deliver GPU access (typically because /dev/dxg is not exposed by the running WSL2 kernel, or the WSLg driver shim mount is missing).

Returned by the WSL2 delegate when wiring /dev/dxg and the WSLg lib mounts into the youki bundle. Silent CPU fallback would be surprising for users who explicitly asked for a GPU, so this is a hard error; callers must either downgrade the spec to drop resources.gpu or re-place the workload on a node whose WSL2 distro exposes the DirectX kernel interface.

Fields

reason: String

GpuSharingUnavailable

GPU sharing was requested (MPS or time-slicing) but the host or runtime cannot satisfy the requested mode.

Typical causes:

• mode = "mps" but the host MPS pipe / log directory does not exist (the nvidia-cuda-mps-control daemon is not running).
• mode = "mps" combined with isolation: hyperv on Windows — MPS is not exposed inside the UVM kernel.

Silent fallback to exclusive-mode access would be surprising for users who explicitly opted in to sharing (they may be relying on sharing for capacity planning), so this is a hard error. Callers must either fix the host (start the MPS daemon, switch isolation) or drop the sharing field from the spec.

Fields

mode: String

Sharing mode that could not be satisfied ("mps", "time-slice").

reason: String

Human-readable explanation (e.g. “/tmp/nvidia-mps does not exist;
ensure nvidia-cuda-mps-control is running”).

RouteToPeer

The workload cannot run on this node and must be re-placed on a peer that can satisfy required_os.

Returned by crate::runtimes::composite::CompositeRuntime::select_for when a foreign-OS workload (today: Linux on a Windows node) lands on a node that has no suitable local runtime (e.g. no WSL2 delegate configured). The scheduler is expected to catch this and re-dispatch to a cluster peer whose NodeState.os matches required_os. When no capable peer exists the scheduler marks the service failed with an actionable message naming both remediations (enable the local WSL2 delegate, or add a Linux peer to the cluster).

This variant is not a container failure: the service manager must surface it to the scheduler and must not roll up CreateFailed on top of it, otherwise the rescheduling signal is lost.

Fields

service: String

Service name that needs to be re-placed.

required_os: String

OS the workload requires (OCI-canonical: linux / windows / darwin).

reason: String

Human-readable explanation (e.g. “no WSL2 delegate configured on this Windows node”).

WrongPlatform

The local runtime cannot service this image because the image’s OS does not match the runtime’s expected OS.

Returned by the HCS runtime when an image’s OCI config reports os != "windows" (e.g. a Linux alpine image landing on a Windows host that also has a WSL2 delegate). Calling vmcompute.dll!ProcessBaseImage on a non-Windows base layer is guaranteed to fail with ERROR_PATH_NOT_FOUND (0x80070003) because the HCS API expects the Windows-specific Hives/ / UtilityVM/ / Files/Windows/System32/ layout. Bailing early with this variant lets the composite runtime treat the call as a soft skip (the delegate’s parallel pull is the one that actually owns the image) instead of failing the whole pull.

This is not a container failure: callers in the composite layer should distinguish this from a real PullFailed and continue with the delegate’s result.

Fields

runtime: String

Identifier of the runtime that rejected the image (e.g. "hcs", "wsl2").

expected: String

OCI-canonical OS this runtime expects (e.g. "windows", "linux").

actual: String

OCI-canonical OS the image manifest reports.

image: String

Image reference that triggered the mismatch.

Trait Implementations

impl Debug for AgentError

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

Formats the value using the given formatter.

impl Display for AgentError

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

Formats the value using the given formatter.

impl Error for AgentError

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.

impl From<DependencyError> for AgentError

fn from(err: DependencyError) -> Self

Converts to this type from the input type.