deepfakes/faceswap · error · Exception

Failed to load image '{filename}'. Original Error: {str(err)

Error message

Failed to load image '{filename}'. Original Error: {str(err)}

What it means

Catch-all branch of read_image_wrap in lib/image.py: any exception other than TypeError/ValueError during image loading (OSError, PermissionError, cv2.error, decompression errors) is logged with the original error, and re-raised as a bare Exception only when raise_error=True. With raise_error=False the function returns None and logs success=False, letting batch pipelines continue.

Source

Thrown at lib/image.py:150

        msg = f"Error while reading image (TypeError): '{filename}'"
        msg += f". Original error message: {str(err)}"
        logger.error(msg)
        if raise_error:
            raise TypeError(msg) from err
    except ValueError as err:
        success = False
        msg = ("Error while reading image. This can be caused by special characters in the "
               f"filename or a corrupt image file: '{filename}'")
        msg += f". Original error message: {str(err)}"
        logger.error(msg)
        if raise_error:
            raise ValueError(msg) from err
    except Exception as err:  # pylint:disable=broad-except
        success = False
        msg = f"Failed to load image '{filename}'. Original Error: {str(err)}"
        logger.error(msg)
        if raise_error:
            raise Exception(msg) from err  # pylint:disable=broad-exception-raised
    logger.trace("Loaded image: '%s'. Success: %s", filename, success)  # type:ignore[attr-defined]
    return retval


@T.overload
def read_image_batch(filenames: list[str], with_metadata: T.Literal[False] = False
                     ) -> np.ndarray: ...


@T.overload
def read_image_batch(filenames: list[str], with_metadata: T.Literal[True]
                     ) -> tuple[np.ndarray, list[PNGHeader]]: ...


def read_image_batch(filenames: list[str], with_metadata: bool = False
                     ) -> np.ndarray | tuple[np.ndarray, list[PNGHeader]]:
    """Load a batch of images from the given file locations.

View on GitHub (pinned to f530cb7508)

Solutions

1. Read the logged 'Original Error' to classify the cause (IO vs permission vs decode) and fix that root cause
2. For batch processing pass raise_error=False and skip/log the None returns so one bad frame does not abort a long job
3. Pre-flight check each file: os.access(path, os.R_OK) and non-zero size before adding it to the batch

Example fix

# before
imgs = [read_image(f, raise_error=True) for f in files]  # one OSError kills the batch

# after
imgs, skipped = [], []
for f in files:
    if not (os.path.isfile(f) and os.access(f, os.R_OK) and os.path.getsize(f) > 0):
        skipped.append(f)
        continue
    im = read_image(f, raise_error=False)
    if im is None:
        skipped.append(f)
    else:
        imgs.append(im)

import os

def preflight_image(path):
    return (os.path.isfile(path)
            and os.access(path, os.R_OK)
            and os.path.getsize(path) > 0)

batch = [f for f in files if preflight_image(f)]

def safe_to_read(path: str) -> bool:
    """True when path exists, is readable and non-empty."""
    import os
    try:
        return os.path.isfile(path) and os.access(path, os.R_OK) and os.path.getsize(path) > 0
    except OSError:
        return False

imgs = []
for f in files:
    img = read_image(f, raise_error=False)
    if img is None:
        logger.warning("skipping unreadable frame: %s", f)
        continue
    imgs.append(img)

When it happens

Trigger: read_image(filename, raise_error=True) where the file is unreadable (PermissionError), deleted mid-read, on a dropped network mount, truncated, or in a format the bundled OpenCV cannot decode (some TIFF/EXR/WebP variants raising cv2.error).

Common situations: Network filesystems dropping during batch reads; files removed by another process mid-run; permission changes on extracted frames; exotic image formats unsupported by the installed OpenCV build.

Related errors

• Error while reading image. This can be caused by special cha
• For arrow image, the minimum size across any axis must be 8
• Error while reading image (TypeError): '{filename}'. Origina
• Landmark based masks cannot be created for {self._landmark_t
• There is a mismatch between the number of frames found in th

AI-assisted analysis of deepfakes/faceswap@f530cb7508 (2026-08-15). Data as JSON: /api/errors/42e84146a7f8cbbb. Report an issue: GitHub.