ocrmypdf/OCRmyPDF · error · ValueError

Unsupported raster device: {raster_device}

Error message

Unsupported raster device: {raster_device}

What it means

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.

Source

Thrown at src/ocrmypdf/builtin_plugins/pypdfium.py:212

        'pngmono',
        'pngmonod',
        'pnggray',
        'png256',
        'png16m',
        'pngalpha',
    )
    format_name: Literal['PNG', 'TIFF', 'JPEG']
    if raster_device_lower in png_devices:
        format_name = 'PNG'
    elif raster_device_lower in ('jpeg', 'jpeggray', 'jpg'):
        format_name = 'JPEG'
    elif raster_device_lower in ('tiff', 'tif'):
        format_name = 'TIFF'
    else:
        # Default to PNG for unknown formats
        format_name = 'PNG'
        if stop_on_soft_error:
            raise ValueError(f"Unsupported raster device: {raster_device}")
        else:
            log.warning(f"Unsupported raster device {raster_device}, using PNG")

    return pil_image, format_name


def _save_image(pil_image: Image.Image, output_file: Path, format_name: str) -> None:
    """Save PIL image to file with appropriate DPI metadata."""
    save_kwargs = {}
    if (
        format_name in ('PNG', 'TIFF')
        and 'dpi' in pil_image.info
        or format_name == 'JPEG'
        and 'dpi' in pil_image.info
    ):
        save_kwargs['dpi'] = pil_image.info['dpi']

    pil_image.save(output_file, format=format_name, **save_kwargs)

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Use a supported raster device name such as 'pngpng', 'pngmono', 'pnggray', 'tiff', 'tif' (case-insensitive).
2. If soft degradation is acceptable, run without stop_on_soft_error so unknown devices fall back to PNG with a warning.

Example fix

# before
rasterize_pdf_page(pdf, page, raster_device='jpeg')
# after
rasterize_pdf_page(pdf, page, raster_device='pngrgb')

SUPPORTED = {'pngpng','pngrgb','pnggray','pngmono','pngalpha','tiff','tif'}
assert raster_device.lower() in SUPPORTED or not stop_on_soft_error

def is_supported_raster_device(d: str) -> bool:
    return d.lower() in {'pngpng','pngrgb','pnggray','pngmono','pngalpha','tiff','tif'}

When it happens

Trigger: 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.

Common situations: Passing a Ghostscript device name (like jpeg or jpeggray) to the pypdfium rasterizer, which only produces PNG/TIFF; mismatched device names in custom pipelines.

Related errors

• Since you specified `--output-type none`, the output file {s
• Invalid color conversion strategy: {options.ghostscript.colo
• At least one provider is required
• --redo-ocr (or --mode redo) is not currently compatible with
• Input file is an image, but the resolution (DPI) is not cred

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/de06ff812a649fde. Report an issue: GitHub.