Stirling-Tools/Stirling-PDF · error · Error

PDFium: failed to load page ${pageIndex}

Error message

PDFium: failed to load page ${pageIndex}

What it means

`getRawPageSize` calls `FPDF_LoadPage(docPtr, pageIndex)`; a null return means the page handle couldn't be created. The most common cause is `pageIndex` being out of range (`< 0` or `>= FPDF_GetPageCount(docPtr)`), but it also fires when the page object in the PDF is structurally damaged.

Source

Thrown at frontend/editor/src/core/services/pdfiumService.ts:370

/**
 * Get page count for a raw document pointer.
 */
export async function getRawPageCount(docPtr: number): Promise<number> {
  const m = await getPdfiumModule();
  return m.FPDF_GetPageCount(docPtr);
}

/**
 * Get raw page dimensions { width, height } for a page.
 */
export async function getRawPageSize(
  docPtr: number,
  pageIndex: number,
): Promise<{ width: number; height: number }> {
  const m = await getPdfiumModule();
  const pagePtr = m.FPDF_LoadPage(docPtr, pageIndex);
  if (!pagePtr) throw new Error(`PDFium: failed to load page ${pageIndex}`);
  const width = m.FPDF_GetPageWidthF(pagePtr);
  const height = m.FPDF_GetPageHeightF(pagePtr);
  m.FPDF_ClosePage(pagePtr);
  return { width, height };
}

/**
 * Read a UTF-16LE string from PDFium memory at the given pointer up to `len`
 * bytes (including the trailing NUL pair).
 */
export function readUtf16(
  m: WrappedPdfiumModule,
  ptr: number,
  byteLen: number,
): string {
  if (byteLen <= 2 || !ptr) return "";
  return m.pdfium.UTF16ToString(ptr);
}

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Validate `0 <= pageIndex < FPDF_GetPageCount(docPtr)` before calling `FPDF_LoadPage`.
2. Re-fetch the page count immediately before the loop rather than trusting a cached value.
3. On failure, read `FPDF_GetLastError()` (code 6 = page error) to distinguish range vs corruption.
4. Guard against a closed/null `docPtr`.

Example fix

// before
const pagePtr = m.FPDF_LoadPage(docPtr, pageIndex);
if (!pagePtr) throw new Error(`PDFium: failed to load page ${pageIndex}`);

// after
const total = m.FPDF_GetPageCount(docPtr);
if (pageIndex < 0 || pageIndex >= total) {
  throw new RangeError(`Page index ${pageIndex} out of range (0..${total - 1})`);
}
const pagePtr = m.FPDF_LoadPage(docPtr, pageIndex);
if (!pagePtr) {
  const err = m.FPDF_GetLastError();
  throw new Error(`PDFium: failed to load page ${pageIndex} (error ${err})`);
}

const count = m.FPDF_GetPageCount(docPtr);
if (pageIndex < 0 || pageIndex >= count) {
  throw new RangeError(`Page ${pageIndex} out of range (0..${count - 1})`);
}

function isInRange(idx: number, count: number): boolean {
  return Number.isInteger(idx) && idx >= 0 && idx < count;
}

When it happens

Trigger: Requesting page index N when the document has fewer pages; passing a negative index; the page dictionary references missing/invalid objects so PDFium can't instantiate it; calling after the document pointer was closed.

Common situations: Stale page count cached before a document was re-saved; iterating with an off-by-one (`<= count` instead of `< count`); a corrupt page in an otherwise-openable PDF.

Related errors

• PDFium: failed to create page
• PDFium: failed to open document (error ${err})
• Expected number
• PDFium: failed to create page
• Failed to load page ${pageIndex}

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/69c14f7e6c96d1d1. Report an issue: GitHub.