{"record":{"id":"de06ff812a649fde","repo":"ocrmypdf/OCRmyPDF","slug":"unsupported-raster-device-raster-device","errorCode":null,"errorMessage":"Unsupported raster device: {raster_device}","messagePattern":"Unsupported raster device: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/builtin_plugins/pypdfium.py","lineNumber":212,"sourceCode":"        'pngmono',\n        'pngmonod',\n        'pnggray',\n        'png256',\n        'png16m',\n        'pngalpha',\n    )\n    format_name: Literal['PNG', 'TIFF', 'JPEG']\n    if raster_device_lower in png_devices:\n        format_name = 'PNG'\n    elif raster_device_lower in ('jpeg', 'jpeggray', 'jpg'):\n        format_name = 'JPEG'\n    elif raster_device_lower in ('tiff', 'tif'):\n        format_name = 'TIFF'\n    else:\n        # Default to PNG for unknown formats\n        format_name = 'PNG'\n        if stop_on_soft_error:\n            raise ValueError(f\"Unsupported raster device: {raster_device}\")\n        else:\n            log.warning(f\"Unsupported raster device {raster_device}, using PNG\")\n\n    return pil_image, format_name\n\n\ndef _save_image(pil_image: Image.Image, output_file: Path, format_name: str) -> None:\n    \"\"\"Save PIL image to file with appropriate DPI metadata.\"\"\"\n    save_kwargs = {}\n    if (\n        format_name in ('PNG', 'TIFF')\n        and 'dpi' in pil_image.info\n        or format_name == 'JPEG'\n        and 'dpi' in pil_image.info\n    ):\n        save_kwargs['dpi'] = pil_image.info['dpi']\n\n    pil_image.save(output_file, format=format_name, **save_kwargs)","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/builtin_plugins/pypdfium.py#L194-L230","documentation":"When rasterizing a page with the pypdfium backend, the requested raster device string is mapped (case-insensitively) to a Pillow save format. Devices other than the known png/tiff family fall through; with stop_on_soft_error enabled, unknown devices raise ValueError instead of degrading to PNG.","triggerScenarios":"Calling rasterize_pdf_page / _process_image_for_output with e.g. raster_device='jpeg' or 'gif' in a strict (stop_on_soft_error) configuration, typically with output_type pdf and certain compression settings.","commonSituations":"Passing a Ghostscript device name (like jpeg or jpeggray) to the pypdfium rasterizer, which only produces PNG/TIFF; mismatched device names in custom pipelines.","solutions":["Use a supported raster device name such as 'pngpng', 'pngmono', 'pnggray', 'tiff', 'tif' (case-insensitive).","If soft degradation is acceptable, run without stop_on_soft_error so unknown devices fall back to PNG with a warning."],"exampleFix":"# before\nrasterize_pdf_page(pdf, page, raster_device='jpeg')\n# after\nrasterize_pdf_page(pdf, page, raster_device='pngrgb')","handlingStrategy":"validation","validationCode":"SUPPORTED = {'pngpng','pngrgb','pnggray','pngmono','pngalpha','tiff','tif'}\nassert raster_device.lower() in SUPPORTED or not stop_on_soft_error","typeGuard":"def is_supported_raster_device(d: str) -> bool:\n    return d.lower() in {'pngpng','pngrgb','pnggray','pngmono','pngalpha','tiff','tif'}","tryCatchPattern":null,"preventionTips":["Don't pass Ghostscript device names (jpeg, jpeggray) to the pypdfium rasterizer.","Fail fast on unknown device strings instead of relying on the PNG fallback."],"tags":["ocrmypdf","pypdfium","raster-device","validation"],"backgroundTag":"unsupported-option-value","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}