Enum Error 

pub enum Error {
    FileNotFound {
        path: PathBuf,
    },
    PasswordRequired {
        path: PathBuf,
    },
    CorruptPdf {
        path: Option<PathBuf>,
        reason: String,
    },
    InvalidPageNumber {
        requested: usize,
        total: usize,
    },
    FontNotFound {
        font_name: String,
    },
    PermissionDenied {
        reason: String,
    },
    UnsupportedPdfVersion {
        version: String,
    },
    FormFieldNotFound {
        field_name: String,
    },
    SignatureVerificationFailed {
        reason: String,
    },
    RedactionFailed {
        reason: String,
    },
    ConversionFailed {
        reason: String,
    },
    InvalidEncoding {
        encoding: String,
    },
    StreamDecodeFailed {
        filter: String,
    },
    XrefCorrupt {
        reason: String,
    },
    LicenseExpired {
        expired_since: String,
    },
    LicenseInvalid {
        reason: String,
    },
    OutputWriteFailed {
        path: PathBuf,
        reason: String,
    },
    ImageDecodeFailed {
        format: String,
    },
    EncryptionFailed {
        reason: String,
    },
    ComplianceViolation {
        standard: String,
        reason: String,
    },
    Io(Error),
    UnsupportedFeature {
        feature: String,
    },
}

Top-level error type for pdf-engine operations.

Each variant maps 1-to-1 to a stable PdfError::code string. Variants carry the minimum fields needed to render a useful message and to give the caller enough context to either retry or surface a clear message to a human.

The std::fmt::Display implementation produces a multi-line, formatted error message including a Help: block and a Docs: link. Use it as format!("{err}") for human consumption; use PdfError::code for programmatic dispatch.

Variants

FileNotFound

The requested file could not be found at the given path. Returned before any parse work is attempted.

Fields

path: PathBuf

The path that was requested but does not exist.

PasswordRequired

The PDF is encrypted and a password is required to open it. The caller should retry with OpenOptions::with_password(...).

Fields

path: PathBuf

The path of the encrypted document.

CorruptPdf

The PDF byte stream could not be parsed. The cross-reference table is malformed, the trailer is unreachable, or a critical object is missing. Try OpenOptions::repair(true) for a best-effort recovery.

Fields

path: Option<PathBuf>

Path to the source file, when known.

reason: String

Human-readable diagnostic of what went wrong (for example “missing trailer”, “bad startxref offset”).

InvalidPageNumber

The caller asked for a page index outside the document’s range. Page numbers are 1-based at the public API.

Fields

requested: usize

The page index the caller requested.

total: usize

How many pages the document actually has.

FontNotFound

A required font could not be located — neither embedded in the PDF, nor on the system, nor in the SDK’s Standard 14 fallback set.

Fields

font_name: String

The PDF base font name that could not be resolved.

PermissionDenied

The requested operation is not allowed by the document’s permission flags. The caller may need an owner password.

Fields

reason: String

Which operation was denied (for example “modify”, “print”).

UnsupportedPdfVersion

The document declares a PDF version this build of the SDK does not understand.

Fields

version: String

The version string from the document header (e.g. "2.1").

FormFieldNotFound

A form-field operation referenced a field that does not exist in the document’s AcroForm dictionary.

Fields

field_name: String

The field name the caller asked for. List actual field names with doc.form_fields().

SignatureVerificationFailed

A digital-signature verification step failed (chain of trust, hash mismatch, expired certificate, etc.).

Fields

reason: String

Specific failure reason from the signing pipeline.

RedactionFailed

A redaction operation could not complete. The document is guaranteed to be unchanged when this is returned (redaction is transactional — failure is total).

Fields

reason: String

Diagnostic of what blocked the redaction.

ConversionFailed

A format conversion (PDF → DOCX, PDF → image, HTML → PDF, etc.) failed before output was produced.

Fields

reason: String

Diagnostic of what blocked the conversion.

InvalidEncoding

A text or string encoding could not be decoded.

Fields

encoding: String

The encoding name that failed (for example "WinAnsiEncoding").

StreamDecodeFailed

A PDF stream could not be decoded — typically because the stream uses an unsupported filter or the encoded payload is corrupt.

Fields

filter: String

The PDF filter name from the stream’s /Filter entry.

XrefCorrupt

The cross-reference table is corrupt or unreadable. Try OpenOptions::repair(true) for a best-effort recovery pass.

Fields

reason: String

Diagnostic of why the xref could not be parsed.

LicenseExpired

The PDFluent license file is past its expiry date. Renew the license or accept the unlicensed-evaluation behaviour.

Fields

expired_since: String

The expiry date the license declared, as an ISO-8601 string.

LicenseInvalid

The license file is malformed, has a bad signature, or is for a different product/key set. The SDK falls back to evaluation mode when this fires unless the caller treats it as a hard error.

Fields

reason: String

Specific reason the license could not be accepted.

OutputWriteFailed

Writing the output document failed (disk full, permission denied, network drive vanished, etc.).

Fields

path: PathBuf

The destination path that was being written.

reason: String

Underlying I/O reason from the OS.

ImageDecodeFailed

An embedded image could not be decoded. Common causes: corrupt JPEG, unknown JPX profile, truncated pixel data.

Fields

format: String

The image format name (for example "JPEG", "JPX").

EncryptionFailed

An encryption operation failed (wrong key, unsupported cipher, invalid permission flags).

Fields

reason: String

Diagnostic of what blocked encryption.

ComplianceViolation

The document violates a declared compliance standard (PDF/A, PDF/UA, PDF/X). Use pdf-compliance to repair if possible.

Fields

standard: String

The compliance standard the document failed against (e.g. "PDF/A-2b").

reason: String

The specific violation that triggered the failure.

Io(Error)

A wrapped std::io::Error from a lower layer. Inspect the inner error for the concrete cause.

UnsupportedFeature

The caller exercised a feature the SDK build does not include (typically a feature-gated capability that was not enabled at compile time).

Fields

feature: String

The feature name (matching the Cargo feature flag where applicable).

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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 Error

fn from(err: Error) -> Self

Converts to this type from the input type.

impl PdfError for Error

fn code(&self) -> &str

Stable machine-readable identifier for the error.

fn help(&self) -> Option<String>

Human-readable, actionable help text.

fn docs_url(&self) -> String

Deep link to the canonical documentation page for this error.