Stirling-Tools/Stirling-PDF · error · Error

Failed to decode image

Error message

Failed to decode image

What it means

Thrown by convertImageToPdf when decodeImageToRgba returns a falsy result, meaning the browser canvas could not decode the image blob into RGBA pixel data. This happens before any PDFium calls, so it is an image-format/canvas problem, not a PDFium problem. The decoded data (rgba buffer, width, height) is required to build the PDF page bitmap.

Source

Thrown at frontend/editor/src/core/utils/imageToPdfUtils.ts:43

    pageFormat = "A4",
    stretchToFit = false,
  } = options;

  try {
    const m = await getPdfiumModule();

    // Read the image file
    let imageBlob: Blob = imageFile;

    // Apply image resolution reduction if requested
    if (imageResolution === "reduced") {
      imageBlob = await reduceImageResolution(imageFile, 1200);
    }

    // Decode image to RGBA pixels via canvas
    const decoded = await decodeImageToRgba(imageBlob);
    if (!decoded) {
      throw new Error("Failed to decode image");
    }

    const { rgba, width: imageWidth, height: imageHeight } = decoded;

    // Determine page dimensions
    let pageWidth: number;
    let pageHeight: number;

    if (pageFormat === "keep") {
      pageWidth = imageWidth;
      pageHeight = imageHeight;
    } else if (pageFormat === "letter") {
      [pageWidth, pageHeight] = PAGE_SIZES.Letter;
    } else {
      [pageWidth, pageHeight] = PAGE_SIZES.A4;
    }

    // Adjust orientation to match image

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Validate the file type against supported canvas-decodable formats (PNG, JPEG, GIF, BMP, WebP) before calling convertImageToPdf.
2. If the format may be unsupported (HEIC/TIFF), transcode it server-side first via the backend convert endpoint.
3. Check the file is non-empty and not corrupt (e.g. load into an Image element and catch onerror).
4. Wrap the call and show a clear 'unsupported image format' message to the user.

Example fix

// before
convertImageToPdf(maybeHeicFile) // canvas can't decode -> throws
// after
const supported = ['image/png','image/jpeg','image/webp','image/gif','image/bmp'];
if (!supported.includes(file.type)) { throw new Error('Unsupported image format. Use PNG, JPEG, WebP, GIF, or BMP.'); }
convertImageToPdf(file);

const CANVAS_DECODABLE = ['image/png', 'image/jpeg', 'image/gif', 'image/bmp', 'image/webp'];

function isCanvasDecodable(file: File): boolean {
  return CANVAS_DECODABLE.includes(file.type) && file.size > 0;
}

if (!isCanvasDecodable(imageFile)) {
  throw new Error('Unsupported or empty image. Use PNG, JPEG, GIF, BMP, or WebP.');
}

function isSupportedImageType(file: File): boolean {
  return CANVAS_DECODABLE.includes(file.type);
}

try {
  await convertImageToPdf(file);
} catch (e) {
  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;
  if (reason.includes('Failed to decode image')) {
    showUser('This image format cannot be decoded in the browser. Try PNG or JPEG, or convert first.');
  } else { throw e; }
}

When it happens

Trigger: Calling convertImageToPdf(file) with a file the browser cannot draw to a canvas: an unsupported/unknown image format, a corrupt image, a zero-byte file, or a format the current browser's canvas does not decode (e.g. certain HEIC/AVIF in older browsers). Also if the blob, after optional resolution reduction, became invalid.

Common situations: User selected a file with an image extension that is actually a different/corrupt format. Browser does not support the image codec (HEIC, some TIFF, exotic AVIF). The file is empty or truncated from a failed download. reduceImageResolution produced an invalid blob.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• No team resolved yet
• Canvas 2D context unavailable
• No automation configuration provided
• Unsupported conversion format
• Response is not a valid PDF. Header: "${head}"

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