{"record":{"id":"46a711bfc51621f9","repo":"Stirling-Tools/Stirling-PDF","slug":"failed-to-decode-image","errorCode":null,"errorMessage":"Failed to decode image","messagePattern":"Failed to decode image","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"frontend/editor/src/core/utils/imageToPdfUtils.ts","lineNumber":43,"sourceCode":"    pageFormat = \"A4\",\n    stretchToFit = false,\n  } = options;\n\n  try {\n    const m = await getPdfiumModule();\n\n    // Read the image file\n    let imageBlob: Blob = imageFile;\n\n    // Apply image resolution reduction if requested\n    if (imageResolution === \"reduced\") {\n      imageBlob = await reduceImageResolution(imageFile, 1200);\n    }\n\n    // Decode image to RGBA pixels via canvas\n    const decoded = await decodeImageToRgba(imageBlob);\n    if (!decoded) {\n      throw new Error(\"Failed to decode image\");\n    }\n\n    const { rgba, width: imageWidth, height: imageHeight } = decoded;\n\n    // Determine page dimensions\n    let pageWidth: number;\n    let pageHeight: number;\n\n    if (pageFormat === \"keep\") {\n      pageWidth = imageWidth;\n      pageHeight = imageHeight;\n    } else if (pageFormat === \"letter\") {\n      [pageWidth, pageHeight] = PAGE_SIZES.Letter;\n    } else {\n      [pageWidth, pageHeight] = PAGE_SIZES.A4;\n    }\n\n    // Adjust orientation to match image","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/frontend/editor/src/core/utils/imageToPdfUtils.ts#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the file type against supported canvas-decodable formats (PNG, JPEG, GIF, BMP, WebP) before calling convertImageToPdf.","If the format may be unsupported (HEIC/TIFF), transcode it server-side first via the backend convert endpoint.","Check the file is non-empty and not corrupt (e.g. load into an Image element and catch onerror).","Wrap the call and show a clear 'unsupported image format' message to the user."],"exampleFix":"// before\nconvertImageToPdf(maybeHeicFile) // canvas can't decode -> throws\n// after\nconst supported = ['image/png','image/jpeg','image/webp','image/gif','image/bmp'];\nif (!supported.includes(file.type)) { throw new Error('Unsupported image format. Use PNG, JPEG, WebP, GIF, or BMP.'); }\nconvertImageToPdf(file);","handlingStrategy":"validation","validationCode":"const CANVAS_DECODABLE = ['image/png', 'image/jpeg', 'image/gif', 'image/bmp', 'image/webp'];\n\nfunction isCanvasDecodable(file: File): boolean {\n  return CANVAS_DECODABLE.includes(file.type) && file.size > 0;\n}\n\nif (!isCanvasDecodable(imageFile)) {\n  throw new Error('Unsupported or empty image. Use PNG, JPEG, GIF, BMP, or WebP.');\n}","typeGuard":"function isSupportedImageType(file: File): boolean {\n  return CANVAS_DECODABLE.includes(file.type);\n}","tryCatchPattern":"try {\n  await convertImageToPdf(file);\n} catch (e) {\n  const reason = (e as Error & { cause?: Error }).cause?.message ?? e.message;\n  if (reason.includes('Failed to decode image')) {\n    showUser('This image format cannot be decoded in the browser. Try PNG or JPEG, or convert first.');\n  } else { throw e; }\n}","preventionTips":["Restrict the file picker to canvas-decodable MIME types.","For HEIC/TIFF, transcode server-side before in-browser conversion.","Reject zero-byte files early.","Test the image in an <img> element and catch onerror as a pre-check."],"tags":["image-to-pdf","canvas","image-decode","validation"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}