Enum ZiPatchError 

#[non_exhaustive]
pub enum ZiPatchError {
    Io(Error),
    InvalidMagic,
    UnknownChunkTag([u8; 4]),
    UnknownSqpkCommand(u8),
    ChecksumMismatch {
        tag: [u8; 4],
        expected: u32,
        actual: u32,
    },
    Decompress(Error),
    InvalidField {
        context: &'static str,
    },
    OversizedChunk(usize),
    UnknownFileOperation(u8),
    Utf8Error(FromUtf8Error),
    BinrwError(Error),
    NegativeFileOffset(i64),
    TruncatedPatch,
}

All failures returned by parsing or applying a ZiPatch stream.

Both the parsing layer (crate::chunk) and the apply layer (crate::apply) surface errors through this single enum, so callers need only one error type in their match arms.

Mapping from standard errors

• std::io::Error converts automatically via #[from] into ZiPatchError::Io.
• std::string::FromUtf8Error converts automatically into ZiPatchError::Utf8Error.
• binrw::Error converts automatically into ZiPatchError::BinrwError.

Example

use zipatch_rs::ZiPatchError;

fn describe(e: &ZiPatchError) -> &'static str {
    match e {
        ZiPatchError::Io(_)               => "I/O error",
        ZiPatchError::InvalidMagic        => "not a ZiPatch file",
        ZiPatchError::UnknownChunkTag(_)  => "unrecognised chunk",
        ZiPatchError::ChecksumMismatch {..}=> "corrupt chunk",
        ZiPatchError::TruncatedPatch      => "download incomplete",
        _                                 => "other error",
    }
}

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.

Io(Error)

Underlying I/O failure from the patch source or target filesystem.

Raised by the parsing layer when reading from the patch stream fails (e.g. a network read error), and by the apply layer when any filesystem operation fails (open, seek, write, delete, create-dir).

The wrapped std::io::Error carries the OS-level error code and kind. Use std::io::Error::kind to distinguish NotFound, PermissionDenied, and similar conditions.

InvalidMagic

The 12-byte ZiPatch magic header was missing or did not match.

Raised by ZiPatchReader::new and ZiPatchReader::from_path when the first 12 bytes of the source do not equal the expected magic sequence \x91ZIPATCH\r\n\x1a\n. Typically indicates the caller opened the wrong file, or the file is corrupted at the very start.

UnknownChunkTag([u8; 4])

A 4-byte chunk tag was not recognised by the parser.

Raised by the chunk dispatcher in crate::chunk when a tag does not match any of FHDR, APLY, APFS, ADIR, DELD, SQPK, or EOF_. The raw tag bytes are preserved so callers can log them for diagnostic purposes.

This can occur with genuinely new chunk types introduced by Square Enix in future patches. Upgrading the library or filing an issue is the appropriate response.

UnknownSqpkCommand(u8)

A SQPK sub-command byte was not recognised by the parser.

Raised by the SQPK dispatcher in crate::chunk when the single-byte command code inside an SQPK chunk does not match any of the known values (A, D, E, F, H, I, T, X). The raw byte is preserved for diagnostics.

ChecksumMismatch

A chunk’s recorded CRC32 did not match the computed CRC32.

Raised by the chunk framing code in crate::chunk when CRC32 verification is enabled (the default) and the stored checksum in the patch stream does not match the checksum computed over tag ++ body.

This indicates a corrupt or partially-written patch file. Disable verification with ZiPatchReader::skip_checksum_verification if the source has already been verified out-of-band.

The tag, expected, and actual fields provide enough information to log a precise diagnostic message.

Fields

tag: [u8; 4]

Tag of the chunk whose checksum failed.

expected: u32

CRC32 stored in the patch file.

actual: u32

CRC32 computed over the actual chunk bytes.

Decompress(Error)

DEFLATE decompression of a SqpkFile block failed.

Raised by the SqpkFile apply logic when flate2 cannot decompress a compressed block payload inside an AddFile operation. The wrapped std::io::Error is the decompressor’s error, not a filesystem error; it is stored as a #[source] rather than #[from] to keep it distinct from ZiPatchError::Io.

InvalidField

A field value failed a parser invariant (e.g. negative size).

Raised by chunk-specific parsers in crate::chunk when a field value is syntactically valid (i.e. could be parsed) but violates a semantic constraint required by the format — for example, a length field that is negative, or a size that overflows the expected range.

The context string names the specific field that failed its check, giving enough information to locate the offending position in the binary format documentation.

Fields

context: &'static str

Human-readable description of which field was invalid and why.

OversizedChunk(usize)

A chunk declared a size larger than the parser’s maximum (512 MiB).

Raised by the chunk framing code in crate::chunk when the body_len field of a chunk frame exceeds 512 MiB. This guard prevents allocating an arbitrarily large buffer from a malformed or malicious patch stream. The preserved size value can be logged for diagnostics.

UnknownFileOperation(u8)

A SqpkFile operation byte was not recognised.

Raised by the SqpkFile parser when the single-byte operation field does not match any of A (AddFile), R (RemoveAll), D (DeleteFile), or M (MakeDirTree). The raw byte is preserved for diagnostics.

Utf8Error(FromUtf8Error)

A UTF-8 decode failed when reading a path or name field.

Raised by the parsing layer when a length-prefixed byte string (e.g. a directory name in an ADIR chunk or a file path in a SqpkFile chunk) is not valid UTF-8. FFXIV patch paths are documented as ASCII, so this error indicates either a corrupt patch file or an undocumented encoding extension.

BinrwError(Error)

A binrw parser produced an error; wraps the underlying cause.

Several chunk types (notably those using #[derive(BinRead)]) delegate their parsing to binrw. When binrw encounters an unexpected byte pattern or short read, it returns a binrw::Error which is wrapped here via #[from].

The inner error message usually identifies the field name and byte offset where parsing failed.

NegativeFileOffset(i64)

A SqpkFile carried a negative file_offset that cannot be applied.

Raised by the AddFile arm of the SqpkFile apply logic when cmd.file_offset is negative and therefore cannot be converted to a u64 seek position. The wire format stores this field as i64; a non-negative value is the invariant required for correct application.

The preserved i64 value can be logged to report the exact field content.

TruncatedPatch

Stream ended without an EOF_ chunk; download or copy was truncated.

Raised by the chunk framing code when attempting to read the 4-byte body_len field of the next chunk returns an unexpected EOF. This indicates the patch stream ended before the mandatory EOF_ terminator chunk was encountered — the patch file was likely incompletely downloaded or written to disk.

Use ZiPatchReader::is_complete after iteration to distinguish this case from a clean end of stream.

Trait Implementations

impl Debug for ZiPatchError

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

Formats the value using the given formatter.

impl Display for ZiPatchError

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

Formats the value using the given formatter.

impl Error for ZiPatchError

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 ZiPatchError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for ZiPatchError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<FromUtf8Error> for ZiPatchError

fn from(source: FromUtf8Error) -> Self

Converts to this type from the input type.