pdfium-errors-binding

name	pdfium-errors-binding
description	Use when pdfium-render fails to load or bind to the Pdfium library: a LoadLibraryError, a panic from Pdfium::default, missing FPDF_* symbols at the first call, or undefined references when statically linking. Prevents shipping a wrong-named or wrong-architecture library, a pdfium_* feature that does not match the binary, and static links missing the C++ runtime or CoreGraphics. Covers PdfiumError::LoadLibraryError, the binding-failure diagnosis matrix, the ordered fix path, and dynamic versus static linking setup. Keywords: pdfium-render LoadLibraryError, library not found, failed to bind Pdfium, Pdfium::default panic, libpdfium.so not found, pdfium.dll missing, missing FPDF symbol, unresolved external symbol, undefined reference libpdfium, FPDFPage_TransformAnnots, pdfium_7763 feature mismatch, static link C++ runtime, libstdc++ libc++, core_graphics macOS, glibc musl mismatch, x64 arm64 mismatch, why does pdfium-render crash on startup
license	MIT
compatibility	Designed for Claude Code. Requires pdfium-render 0.8,0.9.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

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

Variant	Wrapped type	When
LoadLibraryError	libloading::Error	Dynamic binding to the Pdfium library failed. The dominant binding error.
LoadLibraryFunctionNameError	String	Binding failed converting an FPDF_* name to a C string. Rare.
PdfiumLibraryBindingsAlreadyInitialized	unit	Binding attempted when already initialized.

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

Need	Setting
Dynamic link, library beside the executable	bind_to_library(pdfium_platform_library_name_at_path("./"))
Dynamic link, system-installed library	bind_to_system_library()
Static link	static feature + PDFIUM_STATIC_LIB_PATH (directory, not file)
Pin the API version	pdfium_<build> feature matching the binary
C++ runtime for a static build	libstdc++ or libc++ feature
macOS static build	add core_graphics feature
Cross-compile static	PDFIUM_STATIC_LIB_PATH_<triple> per target

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

Mistake	Correct approach
Pdfium::default() in code that must report errors	use bind_to_* + Pdfium::new, match the Result
Library left in the project root, not beside the binary	ship it beside the executable
Renamed or oddly named library file	use the exact platform file name
pdfium_* feature left at a default that mismatches the binary	pin pdfium_<build> to the Chromium build number
Static link without libstdc++ / libc++	enable the C++ runtime feature
macOS static link without core_graphics	enable core_graphics
PDFIUM_STATIC_LIB_PATH pointing at the file	point it at the directory
Re-binding the library on every request	bind once, share via OnceLock

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.