Every error the SDK returns carries a stable code and a link to this section. The code does not change between releases, so it is safe to branch on.
Error::Io
Underlying I/O operation failed.
Check that the file path is accessible and the process has read/write permissions. Inspect `source` for the underlying OS error.
Error::FileNotFound
File not found at the given path.
Verify the path exists before calling. Use `Path::exists()` or handle this variant to prompt the user for the correct path.
Error::InvalidPdf
PDF is structurally invalid.
Ensure the bytes are a complete, undamaged PDF. Check `byte_offset` for the failure site. Re-download or re-export the file if corrupt.
Error::UnsupportedPdfVersion
PDF version is newer than the supported maximum.
The PDF version header exceeds what this build supports. Upgrade to a newer PDFluent release, or pre-process the file with a downgrader.
Error::PdfaValidationFailed
PDF/A validation failed against the requested profile.
Inspect `violations` for specific rule identifiers. Use `OpenOptions::convert_to_pdfa()` to auto-repair, or fix the source document before validation.
Error::DecryptionFailed
Decryption failed — wrong password or unsupported algorithm.
Supply the correct password via `OpenOptions::password()`. Check `reason` to distinguish wrong-password from unsupported-algorithm cases.
Error::InvalidSignature
A digital signature is invalid.
The signature in `field` failed verification. Check `reason` for details. Do not trust the document content if integrity is required.
Error::UnsupportedOnWasm
Operation is not supported in WebAssembly builds.
This operation (`operation`) cannot run in a WASM32 environment. Use the server-side API or guard with `#[cfg(not(target_arch = "wasm32"))]`.
Error::TextEditFailed
A text-edit transaction failed (see [`crate::text_edit`] for the typed per-edit errors this message summarizes).
The message carries the typed reason from the edit session. A stale or invalid match id means the document changed after the search: search again and stage against the new matches. `unsupported container` and `match spans multiple styles` mean the text cannot be edited in place -- redact and re-draw it instead. Overlapping or duplicated stages are a mistake in the caller's own batch.
Error::MissingDependency
A native dependency is required but not installed or discoverable.
Install the missing native library (`dep`) following `install_hint`. Ensure the library is on `LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH`.
Error::MemoryBudgetExceeded
Memory budget set via [`crate::OpenOptions::strict_memory_limit`] exceeded.
Raise the memory limit via `OpenOptions::strict_memory_limit()`, or process the document in smaller chunks.
Error::ResourceLimitExceeded
A processing limit you configured was exceeded while loading or working on the document. The `kind` field says which one.
Inspect `kind` to identify which cap fired, then raise the corresponding `ProcessingLimits` field. For untrusted input, keep limits tight and reject oversized files at the ingestion layer.
Error::PageOutOfRange
A page number outside the document was asked for. Pages are numbered from 1, so 0 is never valid -- it is the number a caller arriving from a 0-based API reaches for first.
Pass a page number between 1 and `page_count()` inclusive. If you are porting from a 0-based API, add 1.
Error::PageRangeInvalid
A page range the document cannot satisfy was asked for: it runs past the last page, starts at 0, or ends before it starts.
Pass a range that lies inside 1..=`page_count()` and does not end before it starts. If you are porting from a 0-based API, add 1 to both ends; `0..n` becomes `1..=n`.
Error::Unsupported
The requested operation is not supported for this document or in this build.
Read the message: it names what was asked for. Either the document lacks the structure the operation needs, or the capability is not part of this build.
Error::Internal
Internal safety-net. Should never fire under normal operation.
This should never occur under normal operation. File a bug report at https://pdfluent.com/support including `message` and `crate_version`.
Returned by the engine and by the C API, which .NET and Java use. This list matches SDK 1.1.0.
pdf_engine::api_error::Error::ComplianceViolation
The document violates a declared compliance standard (PDF/A, PDF/UA, PDF/X).
The document violates the <value> standard. Consider using a compliance repair tool.
pdf_engine::api_error::Error::ConversionFailed
A format conversion (PDF → DOCX, PDF → image, HTML → PDF, etc.) failed before output was produced.
The document could not be converted to the requested format.
pdf_engine::api_error::Error::CorruptPdf
The PDF byte stream could not be parsed.
Try opts.repair(true) to attempt automatic repair.
pdf_engine::EngineError::Encrypted
The PDF is encrypted and requires a password to open.
The PDF is encrypted. Provide the correct password to open it.
pdf_engine::api_error::Error::EncryptionFailed
An encryption operation failed (wrong key, unsupported cipher, invalid permission flags).
Check the encryption parameters and permissions.
pdf_engine::api_error::Error::FileNotFound
The requested file could not be found at the given path.
Check that the file exists and the path is correct. Current directory: <value>
pdf_engine::api_error::Error::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.
Provide a custom font mapping for '<value>', or ensure the font is installed on the system.
pdf_engine::api_error::Error::FormFieldNotFound
A form-field operation referenced a field that does not exist in the document's AcroForm dictionary.
Double-check the field name '<value>' using doc.form_fields().
pdf_engine::api_error::Error::ImageDecodeFailed
An embedded image could not be decoded.
The image format '<value>' could not be decoded.
pdf_engine::api_error::Error::InvalidEncoding
A text or string encoding could not be decoded.
The encoding '<value>' is invalid or unsupported.
pdf_engine::EngineError::Io
Option and selection errors: mistakes in the call, not faults in the document or the engine.
Read the cause with `EngineError::options()`; the variant names the option that was wrong.
pdf_engine::EngineError::InvalidPageGeometry
The page has invalid or degenerate dimensions.
The page has invalid or degenerate dimensions and cannot be rendered.
pdf_engine::api_error::Error::InvalidPageNumber
The caller asked for a page index outside the document's range.
The document has <value> pages. Requested <value>, use a 1-based index up to doc.page_count().
pdf_engine::EngineError::InvalidPdf
The PDF data is invalid or could not be parsed.
The PDF file is corrupt or invalid. Try using a PDF repair tool or re-save the document.
pdf_engine::api_error::Error::Io, pdf_engine::EngineError::Io
A wrapped `std::io::Error` from a lower layer.
Check the underlying I/O error details.
pdf_engine::EngineError::LimitExceeded
A configured resource limit was exceeded during rendering or text extraction.
A processing resource limit was exceeded. Raise the relevant cap in ProcessingLimits or check that the input is not adversarial.
pdf_engine::api_error::Error::OutputWriteFailed
Writing the output document failed (disk full, permission denied, network drive vanished, etc.).
Ensure the destination path is writable and you have sufficient disk space.
pdf_engine::EngineError::PageOutOfRange
A page index is out of range.
Page <value> does not exist. This document has <value> pages (0-<value>).
pdf_engine::api_error::Error::PasswordRequired
The PDF is encrypted and a password is required to open it.
Pass a password when reading the file: let doc = pdfluent::read_with("<value>", |opts| { opts.password("your-password") })?;
pdf_engine::api_error::Error::PermissionDenied
The requested operation is not allowed by the document's permission flags.
The PDF's permissions do not allow this operation. You may need an owner password.
pdf_engine::api_error::Error::RedactionFailed
A redaction operation could not complete.
Ensure coordinates are within page bounds and the document allows redaction.
pdf_engine::EngineError::RenderError
A rendering error occurred.
Rendering failed. Check that the page exists and the document is not corrupted.
pdf_engine::api_error::Error::SignatureVerificationFailed
A digital-signature verification step failed (chain of trust, hash mismatch, expired certificate, etc.).
Check the certificate chain, validity period, and document integrity.
pdf_engine::api_error::Error::StreamDecodeFailed
A PDF stream could not be decoded — typically because the stream uses an unsupported filter or the encoded payload is corrupt.
The stream could not be decoded using filter '<value>'.
pdf_engine::api_error::Error::UnsupportedFeature
The caller exercised a feature the SDK build does not include (typically a feature-gated capability that was not enabled at compile time).
This feature is not yet supported by the PDFluent SDK.
pdf_engine::api_error::Error::UnsupportedPdfVersion
The document declares a PDF version this build of the SDK does not understand.
The SDK currently does not support PDF version <value>.
pdf_engine::EngineError::XfaFlattenFailed
XFA flattening failed.
XFA flattening produced an invalid PDF. The document may use unsupported XFA features.
pdf_engine::api_error::Error::XrefCorrupt
The cross-reference table is corrupt or unreadable.
The cross-reference table is corrupt. Try opts.repair(true).
Thrown as PdfluentError by @pdfluent/sdk-wasm, with message, help and operation on the error. Codes shared with the other bindings are listed above.
Invalid argument passed to a public WASM method.
Page index outside `0..page_count`.
Render call failed.
Vector renderer surfaced an unsupported feature.
Text extraction failed.
XFA flatten/extract failed.
Merge step failed.
Save / serialise step failed.
JSON parse / serialise failure on the WASM boundary.
FormCalc scripting failed.
Creating a digital signature failed.
The pdfluent CLI prints [CODE] message on stderr; with --json the code and message are in the error object. Exit codes: 0 ok, 1 usage, 2 input error, 3 processing error.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 1
Usage error: unknown command or flag, missing required argument, malformed flag value, mutually exclusive options.
exit 1
Usage error: unknown command or flag, missing required argument, malformed flag value, mutually exclusive options.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 1
Usage error: unknown command or flag, missing required argument, malformed flag value, mutually exclusive options.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
The file is present but its SHA-256 differs from the spec.
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
The model dir/file or the runtime library is missing.
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
Anything else: the library would not load, a session would not build, an inference call failed.
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
A second `init` resolving to a different library path.
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 3
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.
exit 1
Usage error: unknown command or flag, missing required argument, malformed flag value, mutually exclusive options.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 2
Input error: missing or unreadable input, corrupt PDF, wrong or missing password, unsupported input type, page range the document cannot satisfy.
exit 3
The library loads but reports a version other than `ORT_VERSION`.
Processing error: the request was well-formed and the input loaded, but the work failed — write errors, conversion failures, facade errors, and capabilities the facade does not expose yet.