# Pdfium Errors Binding

> 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

- Skill: `impertio-studio/pdfium-errors-binding` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add impertio-studio/pdfium-errors-binding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/pdfium-errors-binding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Impertio-Studio (https://skillmd.com/u/impertio-studio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/impertio-studio/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

| 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

```rust
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.