Pdfium Errors Binding

pdfium-errors-binding

Diagnose and fix failures to load and bind the Pdfium library. Binding is step zero of every pdfium-render program: it loads the compiled PDFium library and produces the PdfiumLibraryBindings that Pdfium::new wraps.

Scope: the binding stage only. For the correct binding setup walkthrough see pdfium-core-bindings-setup. For runtime errors after a successful bind (wrong password, corrupt file, bounds errors) see pdfium-errors-runtime. For WASM binding failures see pdfium-impl-wasm.

The one rule that dominates this area

PdfiumError::LoadLibraryError is effectively FATAL. Without a bound Pdfium library NO other pdfium-render call can run. There is no recovery path other than fixing the library setup. ALWAYS handle the binding Result explicitly so the failure produces a clear message instead of a crash.

The binding-failure error variants

PdfiumLibraryInternalError is a RUNTIME error, not a binding error. It belongs to pdfium-errors-runtime.

The diagnosis matrix

Seven root causes produce a binding failure. Identify the one that matches the symptom, then apply its fix.

1. Library not next to the executable

SYMPTOM: LoadLibraryError; works in development, fails when deployed. CAUSE: The library is not next to the executable and not on the system path. FIX: Ship the library beside the executable; bind with pdfium_platform_library_name_at_path("./").

2. Wrong file name for the platform

SYMPTOM: LoadLibraryError although a Pdfium file is present. CAUSE: The file name is not the exact platform name. FIX: Rename to libpdfium.so (Linux), libpdfium.dylib (macOS), or pdfium.dll (Windows).

3. Architecture or ABI mismatch

SYMPTOM: LoadLibraryError reporting an incompatible binary, or an instant crash. CAUSE: x64 against arm64, arm64 against x64, or glibc against musl. FIX: Download the archive matching the host platform, architecture, AND libc.

4. pdfium_* feature does not match the binary

SYMPTOM: Binding succeeds, then the FIRST real call fails with a missing symbol or crashes. CAUSE: The pdfium_* crate feature selects a PDFium API version that differs from the bound binary's Chromium build. FIX: Read the Chromium build number from the binary's release tag (chromium/<number>) and set the matching pdfium_* feature, for example pdfium_7763. This is the most common silent binding fault.

5. Windows static link: unresolved external symbols

SYMPTOM: A linker error naming an FPDF_* symbol such as FPDFPage_TransformAnnots (issue #173). CAUSE: The static archive predates the API version the pdfium_* feature expects. FIX: Use a pdfium.lib whose Chromium build matches the pdfium_* feature.

6. Static link missing the C++ runtime

SYMPTOM: A wall of undefined-reference linker errors on a static build (issues #51, #12). CAUSE: PDFium is C++; the static link did not include a C++ standard library. FIX: Enable the libstdc++ feature, or the libc++ feature, matching the toolchain.

7. macOS static link missing CoreGraphics

SYMPTOM: Undefined symbols _CGBitmap / _CGContext on a macOS static build. CAUSE: PDFium's macOS build calls CoreGraphics, which was not linked. FIX: Enable the core_graphics crate feature.

Each row is expanded with full detail in references/anti-patterns.md.

The ordered fix path

When the cause is not obvious, work through the checks IN THIS ORDER. Each step rules out one class of failure.

1. Confirm the file NAME
     libpdfium.so / libpdfium.dylib / pdfium.dll, exact spelling.
2. Confirm the ARCHITECTURE
     host platform, CPU arch, and libc (glibc vs musl) all match the binary.
3. Confirm the pdfium_* FEATURE
     the crate feature matches the binary's Chromium build number.
4. Add the LINK FEATURES (static builds only)
     libstdc++ or libc++ for the C++ runtime; core_graphics on macOS.

Steps 1 to 3 cover dynamic linking. Step 4 applies only to static linking.

Prevention: bind gracefully, never panic

use pdfium_render::prelude::*;

let bindings = Pdfium::bind_to_library(
    Pdfium::pdfium_platform_library_name_at_path("./"),
)
.or_else(|_| Pdfium::bind_to_system_library())?;   // returns Result
let pdfium = Pdfium::new(bindings);

The three bind_to_* functions return Result<Box<dyn PdfiumLibraryBindings>, PdfiumError>. Matching the Result turns a missing library into a clear, reported error.

NEVER use Pdfium::default() where a missing library must be handled. default() returns Self, not Result, and its doc comment states it PANICS when no suitable library can be loaded. It is acceptable only in throwaway scripts.

Linking quick reference

PDFIUM_STATIC_LIB_PATH and PDFIUM_DYNAMIC_LIB_PATH ALWAYS point at the DIRECTORY containing the library, never at the file. Full reference data is in references/methods.md.

Common mistakes

Reference files

• references/methods.md: binding API, error variants, platform reference data.
• references/examples.md: working bind patterns and linking configuration.
• references/anti-patterns.md: the seven failure modes, expanded with fixes.

Related skills

• pdfium-core-bindings-setup: the correct binding setup walkthrough.
• pdfium-errors-runtime: errors after a successful bind.
• pdfium-impl-wasm: WASM-specific binding failures.
• pdfium-impl-performance: the bind-once production pattern.