{"record":{"id":"e7a15a0c7cf75ec4","repo":"ocrmypdf/OCRmyPDF","slug":"the-input-image-has-an-alpha-channel-remove-the-a","errorCode":null,"errorMessage":"The input image has an alpha channel. Remove the alpha channel first.","messagePattern":"The input image has an alpha channel\\. Remove the alpha channel first\\.","errorType":"error_code","errorClass":"UnsupportedImageFormatError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/_pipeline.py","lineNumber":124,"sourceCode":"        if 'dpi' in im.info:\n            if im.info['dpi'] <= (96, 96) and not options.image_dpi:\n                log.info(\"Image size: (%d, %d)\", *im.size)\n                log.info(\"Image resolution: (%d, %d)\", *im.info['dpi'])\n                raise DpiError(\n                    \"Input file is an image, but the resolution (DPI) is \"\n                    \"not credible.  Estimate the resolution at which the \"\n                    \"image was scanned and specify it using --image-dpi.\"\n                )\n        elif not options.image_dpi:\n            log.info(\"Image size: (%d, %d)\", *im.size)\n            raise DpiError(\n                \"Input file is an image, but has no resolution (DPI) \"\n                \"in its metadata.  Estimate the resolution at which \"\n                \"image was scanned and specify it using --image-dpi.\"\n            )\n\n        if im.mode in ('RGBA', 'LA'):\n            raise UnsupportedImageFormatError(\n                \"The input image has an alpha channel. Remove the alpha channel first.\"\n            )\n\n        if 'iccprofile' not in im.info:\n            if im.mode == 'RGB':\n                log.info(\"Input image has no ICC profile, assuming sRGB\")\n            elif im.mode == 'CMYK':\n                raise UnsupportedImageFormatError(\n                    \"Input CMYK image has no ICC profile, not usable\"\n                )\n\n    try:\n        log.info(\"Image seems valid. Try converting to PDF...\")\n        layout_fun = img2pdf.default_layout_fun\n        if options.image_dpi:\n            layout_fun = img2pdf.get_fixed_dpi_layout_fun(\n                Resolution(options.image_dpi, options.image_dpi)\n            )","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/_pipeline.py#L106-L142","documentation":"Raised when the input image mode is RGBA or LA, i.e. it has an alpha (transparency) channel. img2pdf cannot embed alpha channels into a PDF image, so the alpha must be removed before conversion.","triggerScenarios":"Input image with mode 'RGBA' or 'LA' (PNG with transparency most commonly); checked in triage_image_file before img2pdf conversion.","commonSituations":"PNG exports from design tools or screenshots with transparency; logos or web images.","solutions":["Flatten the image onto a white background and save without alpha","Convert to RGB mode before running ocrmypdf"],"exampleFix":"# before\nocrmypdf logo.png out.pdf\n# after (Python)\nfrom PIL import Image\nim = Image.open('logo.png').convert('RGB')\nim.save('logo_rgb.png')\n# then: ocrmypdf logo_rgb.png out.pdf","handlingStrategy":"validation","validationCode":"from PIL import Image\nwith Image.open(src) as im:\n    if im.mode in ('RGBA', 'LA'):\n        bg = Image.new('RGB', im.size, (255, 255, 255))\n        bg.paste(im, mask=im.split()[-1])\n        bg.save(src)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Flatten alpha in your preprocessing pipeline for all PNG inputs"],"tags":["ocr","ocrmypdf","image-format","alpha-channel"],"backgroundTag":"unsupported-image-format","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}