calesthio/OpenMontage · error · ValueError

Could not read image: {input_path}

Error message

Could not read image: {input_path}

What it means

ValueError raised by the upscaler's _upscale_image when cv2.imread returns None. OpenCV silently returns None (instead of raising) for unreadable files — missing path, unsupported/corrupt format, or a format the opencv build lacks codecs for (e.g. 16-bit PNGs, some TIFF variants, WebP on minimal builds). The explicit check converts that silent None into a clear message naming the path.

Source

Thrown at tools/enhancement/upscale.py:194

    # Image upscaling
    # ------------------------------------------------------------------

    def _upscale_image(
        self,
        input_path: Path,
        output_path: Path,
        scale: int,
        model_name: str,
        face_enhance: bool,
        denoise_strength: float,
    ) -> dict[str, Any]:
        import cv2

        upsampler = self._build_upsampler(scale, model_name, denoise_strength, face_enhance)

        img = cv2.imread(str(input_path), cv2.IMREAD_UNCHANGED)
        if img is None:
            raise ValueError(f"Could not read image: {input_path}")

        output, _ = upsampler.enhance(img, outscale=scale)
        cv2.imwrite(str(output_path), output)

        h, w = output.shape[:2]
        return {"output_width": w, "output_height": h}

    # ------------------------------------------------------------------
    # Video upscaling
    # ------------------------------------------------------------------

    def _upscale_video(
        self,
        input_path: Path,
        output_path: Path,
        scale: int,
        model_name: str,
        face_enhance: bool,

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Check `input_path.exists()` and that it is a non-empty regular file before calling upscale.
2. Re-encode the image to PNG/JPEG with an external tool (Pillow, ffmpeg, ImageMagick) if the source is HEIC/AVIF/exotic TIFF.
3. Verify OpenCV can decode it standalone: `python -c "import cv2; print(cv2.imread('file.png') is not None)"`.
4. Confirm the path is absolute or resolved against the intended base directory — imread does not error on relative-path mistakes, it just returns None.

Example fix

# before
result = tool.run(input_path=Path("photo.heic"), ...)  # cv2.imread -> None -> ValueError

# after
from PIL import Image
input_path = Path("photo.heic")
if input_path.suffix.lower() not in {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tiff"}:
    input_path = input_path.with_suffix(".png")
    Image.open("photo.heic").save(input_path)
result = tool.run(input_path=input_path, ...)

from pathlib import Path
import cv2

def readable_image(path: Path) -> bool:
    return path.is_file() and path.stat().st_size > 0 and cv2.imread(str(path)) is not None

try:
    result = tool.run(input_path=p, ...)
except ValueError as e:
    if "Could not read image" in str(e):
        raise ValueError(f"Unsupported/corrupt image {p}; convert to PNG or JPEG first") from e
    raise

When it happens

Trigger: Calling the upscale tool with input_path that does not exist, has an unexpected extension (.heic, .avif), is a directory, is a zero-byte/corrupt file, or is encoded in a format the installed opencv-python cannot decode.

Common situations: Passing user uploads without validation, path resolution bugs (relative paths resolved against the wrong cwd), filenames with special characters mishandled by shell/quoting, or opencv-python-headless builds without codec support for exotic formats.

Related errors

• unknown project: {project_id}
• Unsupported Atlas image model id {model!r}. Use get_info()['
• {family} does not expose generation_mode={operation!r} on At
• ${res.status} ${url}
• fetch failed ${r.status}: ${url}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/4ce72507d6954c99. Report an issue: GitHub.