Enum BuildError 

pub enum BuildError {
    DockerfileParse {
        message: String,
        line: usize,
    },
    ContextRead {
        path: PathBuf,
        source: Error,
    },
    PathEscape {
        path: PathBuf,
    },
    FileIgnored {
        path: PathBuf,
    },
    StageNotFound {
        name: String,
    },
    RunFailed {
        command: String,
        exit_code: i32,
    },
    LayerCreate {
        message: String,
    },
    CacheError {
        message: String,
    },
    RegistryError {
        message: String,
    },
    BinfmtNotRegistered {
        platform: String,
        qemu_arch: String,
    },
    IoError(Error),
    VariableExpansion(String),
    InvalidInstruction {
        instruction: String,
        reason: String,
    },
    BuildahExecution {
        command: String,
        exit_code: i32,
        stderr: String,
    },
    ContextTooLarge {
        size: u64,
        max: u64,
    },
    BaseImageNotFound {
        image: String,
    },
    CircularDependency {
        stages: Vec<String>,
    },
    BuildahNotFound {
        message: String,
    },
    ZImagefileParse {
        message: String,
    },
    ZImagefileValidation {
        message: String,
    },
    PipelineError {
        message: String,
    },
    WasmBuild(WasmBuildError),
    NotSupported {
        operation: String,
    },
    NotYetImplemented(String),
    SandboxNeedsLinux {
        command: String,
        reason: String,
    },
    RunStepFailed {
        step_index: usize,
        exit_code: i32,
        stderr_tail: String,
    },
    LayerExportFailed {
        source: Error,
    },
    ChocoResolutionFailed {
        package: String,
        source_distro: String,
    },
    PathTraversal {
        src: String,
    },
    HttpFetchFailed {
        url: String,
        source: Error,
    },
    TarExtractFailed {
        source: Error,
    },
    OsVersionUnresolved,
    LayerDigestComputationFailed {
        source: Error,
    },
    SerializeManifestFailed {
        source: Error,
    },
    PushFailed {
        tag: String,
        reason: String,
    },
    BlobUploadFailed {
        digest: String,
        tag: String,
        reason: String,
    },
    ManifestPutFailed {
        tag: String,
        reason: String,
    },
}

Build-specific errors

Variants

DockerfileParse

Dockerfile parsing failed

Fields

message: String

The underlying parsing error message

line: usize

Line number where the error occurred (1-indexed)

ContextRead

Failed to read build context

Fields

path: PathBuf

Path that could not be read

source: Error

Underlying IO error

PathEscape

Path escape attempt detected (security violation)

Fields

path: PathBuf

The offending path

FileIgnored

File was ignored by .dockerignore

Fields

path: PathBuf

The ignored file path

StageNotFound

Referenced stage not found

Fields

name: String

The stage name or index that was referenced

RunFailed

RUN instruction failed

Fields

command: String

The command that failed

exit_code: i32

Exit code returned by the command

LayerCreate

Failed to create layer

Fields

message: String

Underlying error description

CacheError

Cache operation failed

Fields

message: String

Underlying cache error

RegistryError

Registry operation failed

Fields

message: String

Underlying registry error

BinfmtNotRegistered

A cross-architecture build was requested but the host has no binfmt_misc / qemu-user-static handler registered for the target architecture, so buildah cannot execute foreign-arch RUN steps.

Fields

platform: String

The platform string that was requested (e.g. linux/arm64).

qemu_arch: String

The qemu-user-static handler arch name expected under /proc/sys/fs/binfmt_misc/qemu-<arch> (e.g. aarch64).

IoError(Error)

IO error

VariableExpansion(String)

Variable expansion failed

InvalidInstruction

Invalid instruction

Fields

instruction: String

The instruction that was invalid

reason: String

Reason why it was invalid

BuildahExecution

Buildah command execution failed

Fields

command: String

The buildah command that failed

exit_code: i32

Exit code from buildah

stderr: String

Standard error output

ContextTooLarge

Build context too large

Fields

size: u64

Actual size in bytes

max: u64

Maximum allowed size

BaseImageNotFound

Base image not found

Fields

image: String

The image reference that was not found

CircularDependency

Circular dependency in multi-stage build

Fields

stages: Vec<String>

The stages involved in the cycle

BuildahNotFound

Buildah binary not found or installation failed

Fields

message: String

Details about the failure

ZImagefileParse

ZImagefile YAML deserialization failed

Fields

message: String

The underlying YAML parse error message

ZImagefileValidation

ZImagefile semantic validation failed

Fields

message: String

Description of what validation rule was violated

PipelineError

Pipeline validation or execution error

Fields

message: String

Description of the pipeline error

WasmBuild(WasmBuildError)

WASM build failed

NotSupported

Operation not supported by this backend

Fields

operation: String

The operation that was attempted

NotYetImplemented(String)

A code path that is reserved for a future phase / task and is intentionally not yet wired up. Constructed by BuildError::not_yet_implemented so call sites can give a precise reason (typically referencing the follow-up task that delivers it, e.g. “RUN execution lands in Phase 4 task 4.B”).

This is distinct from BuildError::NotSupported, which signals a permanent capability gap of the chosen backend; NotYetImplemented signals “tracked work, coming in a later task — do not silently no-op”.

SandboxNeedsLinux

A macOS sandbox build step cannot be performed natively because it genuinely needs a Linux environment — a Linux toolchain / libc / kernel headers, a Linux-only package with no Homebrew bottle, or a Linux ELF binary that cannot execute on Darwin.

Distinct from BuildError::RunFailed (a command that actually ran and exited non-zero — i.e. a user error) and from BuildError::NotSupported (a permanent backend capability gap): SandboxNeedsLinux signals “this is faithfully buildable, just not here — retry on the buildd-in-VZ Linux path”. The build front-end keys its sandbox -> VZ-Linux fallback off this variant, so it must NOT be raised for a broken command and must NOT be swallowed as a silent success.

Fields

command: String

The RUN command (or build step) that requires Linux.

reason: String

Why Linux is required: the unresolved package/formula, the detected Linux ELF binary, or the toolchain dependency.

RunStepFailed

A specific RUN step in a Dockerfile failed with a non-zero exit code. Carries the step index (0-based, counted across the active stage’s instruction list), the exit code surfaced by the guest process, and a stderr tail to anchor diagnostics.

Distinct from BuildError::RunFailed in that the latter is emitted by the buildah/HCS backends working through the BuildBackend trait, whereas this variant is emitted by the Phase 4 WindowsBuilder path which carries a richer per-step context (the step index and a stderr tail) than the buildah path can produce.

Fields

step_index: usize

Zero-based step index within the active stage’s instruction list (the value Phase 4 errors use to anchor a diagnostic).

exit_code: i32

Exit code reported by the guest process.

stderr_tail: String

Last fragment of stderr captured during the RUN step (or a synthesised message when pipe capture has not yet been wired). Surfaced verbatim in the error display so users get the failing command in their build log.

LayerExportFailed

HcsExportLayer / wclayer-side IO failed while capturing the post-RUN scratch diff. Distinct from BuildError::IoError so the WCOW builder can surface a layer-export-specific message (the underlying failure is almost always either an HcsExportLayer HRESULT or a tar/gzip walk error).

Fields

source: Error

Underlying IO error (often wraps an HCS HRESULT).

ChocoResolutionFailed

Chocolatey resolver could not produce a Windows equivalent for a Linux package name encountered in a RUN instruction. The package is named so the user can edit the Dockerfile (or contribute the mapping to RepoSources).

Fields

package: String

The Linux package name that did not resolve.

source_distro: String

The RepoSources-style source distro key that was queried (e.g. "debian-12", "ubuntu-22.04").

PathTraversal

COPY/ADD source path contained a .. component which is forbidden because it would escape the build context. Surfaced before any filesystem access so a malicious Dockerfile cannot reach files outside the build directory even via a TOCTOU window.

Fields

src: String

The offending source path as it appeared in the Dockerfile.

HttpFetchFailed

ADD <URL> <dest> failed to download the remote resource. Carries the URL for diagnostics; the underlying network/protocol failure is chained as the source so users get the precise cause (connection refused, 404, TLS error, etc.).

Fields

url: String

The URL the builder attempted to fetch.

source: Error

Underlying reqwest failure.

TarExtractFailed

ADD auto-extraction of a tarball failed. Carries the chained IO error from the tar / flate2 / bzip2 / xz2 pipeline so the user can see which entry tripped (path traversal in the archive, disk full, etc.).

Fields

source: Error

Underlying tar/decompressor IO error.

OsVersionUnresolved

The WCOW builder could not resolve an os.version for the emitted OCI image config. The Windows runtime refuses to launch a container whose os.version does not exactly match the host kernel’s build, so emitting a manifest without one would produce an image nothing can run. Surfaces when the base manifest’s os.version is missing AND the user did not pass WindowsBuildConfig::os_version_override.

LayerDigestComputationFailed

Computing a sha256 digest over a layer blob (or an in-memory manifest blob) failed because the underlying IO read failed. Carries the chained IO error so callers can see which file tripped.

Fields

source: Error

Underlying IO error.

SerializeManifestFailed

JSON serialisation of the emitted OCI image config or manifest blob failed. In practice this only happens if a value carried on the crate::windows_builder::OciImageConfig is itself unserialisable, which is a programmer error in this crate.

Fields

source: Error

Underlying serde_json error.

PushFailed

Top-level wrapper for any failure during the WCOW crate::windows_builder::WindowsBuilder::push flow. Returned when the push could not be completed but the failure is not better described by BuildError::BlobUploadFailed or BuildError::ManifestPutFailed — for example, when reading a local layer blob off disk fails before it ever reaches the wire.

Fields

tag: String

Target image tag the push was destined for, e.g. "ghcr.io/zorpxinc/zlayer-test:wcow-0.1".

reason: String

Human-readable failure reason from the upstream layer.

BlobUploadFailed

A single layer blob upload PUT/PATCH chain failed. Carries the blob’s content-addressable digest so the operator can correlate against registry-side logs.

Fields

digest: String

sha256:... digest of the blob that failed to upload.

tag: String

Target image tag.

reason: String

Human-readable failure reason from the upstream layer.

ManifestPutFailed

The final PUT /v2/<name>/manifests/<tag> request failed. Distinct from BuildError::BlobUploadFailed because the manifest PUT is the last write that makes the push observable from the registry — a failure here means the layers and config blob may be staged but the image is not yet visible under tag.

Fields

tag: String

Target image tag the manifest PUT targeted.

reason: String

Human-readable failure reason from the upstream layer.

Implementations

impl BuildError

pub fn parse_error(msg: impl Into<String>, line: usize) -> Self

Create a DockerfileParse error from a message and line number

pub fn context_read(path: impl Into<PathBuf>, source: Error) -> Self

Create a ContextRead error from a path and IO error

pub fn path_escape(path: impl Into<PathBuf>) -> Self

Create a PathEscape error

pub fn stage_not_found(name: impl Into<String>) -> Self

Create a StageNotFound error

pub fn run_failed(command: impl Into<String>, exit_code: i32) -> Self

Create a RunFailed error

pub fn layer_create(msg: impl Into<String>) -> Self

Create a LayerCreate error

pub fn cache_error(msg: impl Into<String>) -> Self

Create a CacheError

pub fn registry_error(msg: impl Into<String>) -> Self

Create a RegistryError

pub fn invalid_instruction( instruction: impl Into<String>, reason: impl Into<String>, ) -> Self

Create an InvalidInstruction error

pub fn buildah_execution( command: impl Into<String>, exit_code: i32, stderr: impl Into<String>, ) -> Self

Create a BuildahExecution error

pub fn buildah_not_found(message: impl Into<String>) -> Self

Create a BuildahNotFound error

pub fn zimagefile_parse(message: impl Into<String>) -> Self

Create a ZImagefileParse error

pub fn zimagefile_validation(message: impl Into<String>) -> Self

Create a ZImagefileValidation error

pub fn pipeline_error(message: impl Into<String>) -> Self

Create a PipelineError

pub fn not_yet_implemented(msg: impl Into<String>) -> Self

Create a NotYetImplemented error. The msg should name the follow-up task or phase that delivers the missing behavior (e.g. "RUN execution lands in Phase 4 task 4.B").

pub fn sandbox_needs_linux( command: impl Into<String>, reason: impl Into<String>, ) -> Self

Create a SandboxNeedsLinux error signalling the build front-end to fall back to the buildd-in-VZ Linux path.

Trait Implementations

impl Debug for BuildError

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

Formats the value using the given formatter.

impl Display for BuildError

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

Formats the value using the given formatter.

impl Error for BuildError

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<Error> for BuildError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<ToolchainError> for BuildError

Convert a zlayer-toolchain error into a BuildError.

The toolchain crate (the macOS keg provisioner — source build + prebuilt fetch) is a leaf crate, extracted from this crate to break the builder<->agent build cycle. Its errors flow back through ? at the builder call sites (e.g. ensure_toolchain(..).await? when materializing a keg into a build rootfs), so they need a From bridge. The IoError arm is preserved structurally; everything else folds into RegistryError carrying the rendered message.

fn from(err: ToolchainError) -> Self

Converts to this type from the input type.

impl From<WasmBuildError> for BuildError

fn from(source: WasmBuildError) -> Self

Converts to this type from the input type.