ocrmypdf/OCRmyPDF · error · ValueError

Invalid color conversion strategy: {options.ghostscript.colo

Error message

Invalid color conversion strategy: {options.ghostscript.color_conversion_strategy}

What it means

Ghostscript's color conversion strategy must be one of the values Ghostscript supports (ghostscript.COLOR_CONVERSION_STRATEGIES, e.g. LeaveColorUnchanged, RGB, CMYK, Gray ...). check_options() validates options.ghostscript.color_conversion_strategy and raises ValueError for anything else.

Source

Thrown at src/ocrmypdf/builtin_plugins/ghostscript.py:227

                "(or --mode force) to discard existing text."
            )
        if ghostscript.jpeg_truncation_bug(gs_version):
            log.warning(
                "Ghostscript %s contains JPEG encoding errors that may corrupt "
                "images. OCRmyPDF will attempt to mitigate, but this version is "
                "strongly not recommended. Please upgrade to Ghostscript %s or "
                "later, which fixes this.",
                gs_version,
                ghostscript.GS_JPEG_TRUNCATION_FIXED,
            )
        if options.output_type == 'pdfa':
            options.output_type = 'pdfa-2'

    if (
        options.ghostscript.color_conversion_strategy
        not in ghostscript.COLOR_CONVERSION_STRATEGIES
    ):
        raise ValueError(
            f"Invalid color conversion strategy: "
            f"{options.ghostscript.color_conversion_strategy}"
        )
    if (
        options.ghostscript.pdfa_image_compression != 'auto'
        and options.output_type not in ('auto', 'pdfa', 'pdfa-1', 'pdfa-2', 'pdfa-3')
    ):
        log.warning(
            "--pdfa-image-compression argument only applies when "
            "--output-type is 'auto' or one of 'pdfa', 'pdfa-1', 'pdfa-2', 'pdfa-3'"
        )


@hookimpl
def rasterize_pdf_page(
    input_file,
    output_file,
    raster_device,

View on GitHub (pinned to 5074a0b0e1)

Solutions

Use one of the exact supported names, e.g. 'LeaveColorUnchanged', 'RGB', 'Gray', 'CMYK', 'UseDeviceIndependentColor' (check ghostscript.COLOR_CONVERSION_STRATEGIES for your version).
Confirm the option is nested under the ghostscript sub-namespace, not passed as a top-level kwarg.

Example fix

# before
ocr(in, out, ghostscript={'color_conversion_strategy': 'leaveunchanged'})
# after
ocr(in, out, ghostscript={'color_conversion_strategy': 'LeaveColorUnchanged'})

Defensive patterns

Strategy: validation

Validate before calling

from ocrmypdf.builtin_plugins.ghostscript import COLOR_CONVERSION_STRATEGIES
assert strategy in COLOR_CONVERSION_STRATEGIES

Type guard

def is_valid_color_strategy(s: str) -> bool:
    from ocrmypdf.builtin_plugins.ghostscript import COLOR_CONVERSION_STRATEGIES
    return s in COLOR_CONVERSION_STRATEGIES

Prevention

Always source strategy names from COLOR_CONVERSION_STRATEGIES rather than hardcoding strings.
Use exact CamelCase values like 'LeaveColorUnchanged'.

When it happens

Trigger: Setting the kwarg path ghostscript={'color_conversion_strategy': 'leave_color_unchanged'} (wrong spelling/case) or a nonexistent strategy string.

Common situations: Copying strategy names from old blog posts or CLI flags with underscores instead of CamelCase; typos like 'RGB ' with trailing whitespace.

Understand the failure class

Background: Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained — this error's family across 23 libraries.

Related errors

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