Stirling-Tools/Stirling-PDF · warning · Error

PDFium: failed to render page 0

Error message

PDFium: failed to render page 0

What it means

Thrown in generatePdfiumThumbnail (single-thumbnail variant) when renderPdfiumPageDataUrl(docPtr, 0, scale, {applyRotation}) returned null/falsy. The document opened successfully (password errors are caught earlier), so a null render means PDFium could not rasterize page 0 — corrupt page content, unsupported PDF features crashing the WASM render, zero-size page geometry, or scale producing a 0x0 bitmap.

Source

Thrown at frontend/editor/src/core/utils/thumbnailUtils.ts:124

      new RegExp(`error ${PDFIUM_ERR_PASSWORD}`).test(error.message)
    ) {
      return {
        thumbnail: "",
        pageCount: 1,
        pageRotations: [],
        pageDimensions: [],
        isEncrypted: true,
      };
    }
    throw error;
  }

  try {
    const pageCount = m.FPDF_GetPageCount(docPtr);
    const thumbnail = await renderPdfiumPageDataUrl(docPtr, 0, scale, {
      applyRotation,
    });
    if (!thumbnail) throw new Error("PDFium: failed to render page 0");

    // Page 0 metadata is already available via the render, but read it
    // directly for consistency with the later per-page loop.
    const firstMeta = await readPdfiumPageMetadata(docPtr, 0);
    const pageRotations: number[] = [firstMeta?.rotation ?? 0];
    const pageDimensions: Array<{ width: number; height: number }> = [
      {
        width: firstMeta?.width ?? 0,
        height: firstMeta?.height ?? 0,
      },
    ];

    if (collectAllPagesMetadata) {
      for (let i = 1; i < pageCount; i++) {
        const meta = await readPdfiumPageMetadata(docPtr, i);
        if (!meta) continue;
        pageRotations[i] = meta.rotation;
        pageDimensions[i] = { width: meta.width, height: meta.height };

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Clamp scale to a minimum positive value before rendering.
2. Validate page dimensions (readPdfiumPageMetadata) are positive before rendering; if not, return an empty-thumbnail placeholder.
3. On null render, fall back to a placeholder thumbnail and continue loading rather than failing the whole import.
4. Ensure the WASM module heap is large enough for the rasterized bitmap.

Example fix

// before
const thumbnail = await renderPdfiumPageDataUrl(docPtr, 0, scale, { applyRotation });
if (!thumbnail) throw new Error("PDFium: failed to render page 0");

// after
const thumbnail = await renderPdfiumPageDataUrl(docPtr, 0, scale, { applyRotation });
if (!thumbnail) {
  // Return a placeholder so import continues; surface a non-fatal warning instead of aborting.
  return { thumbnail: "", pageCount, pageRotations: [], pageDimensions: [], isEncrypted: false, renderFailed: true };
}

const meta = await readPdfiumPageMetadata(docPtr, 0);
if (!meta || meta.width <= 0 || meta.height <= 0) {
  // skip render, return placeholder
}
const safeScale = scale > 0 ? scale : 0.2;

const hasValidPageGeometry = (m: { width: number; height: number } | null): m is { width: number; height: number } =>
  !!m && m.width > 0 && m.height > 0;

try {
  const thumb = await generatePdfiumThumbnail(data, scale);
} catch (error) {
  if (/failed to render page 0/.test((error as Error).message)) {
    return { thumbnail: "", pageCount: 1, pageRotations: [], pageDimensions: [], renderFailed: true };
  }
  throw error;
}

When it happens

Trigger: A PDF whose page 0 has no/zero dimensions; scale resolved to 0 from a degenerate thumbnail-size config; a PDF using features the bundled PDFium build cannot render; WASM memory exhaustion during rasterization.

Common situations: Thumbnail generation at import time for an unusual/corrupt PDF; very low thumbnail target size; PDFs from generators PDFium partially supports.

Related errors

• PDFium: failed to create document
• Failed to process ${file.name}: ${error instanceof Error ? e
• PDFium: failed to create destination document
• PDFium: failed to create document
• PDFium: failed to create page

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