deepfakes/faceswap · error · FaceswapError

For arrow image, the minimum size across any axis must be 8

Error message

For arrow image, the minimum size across any axis must be 8 and dimensions must all be divisible by 2

What it means

lib/image.py read_image_wrap catches TypeError from the cv2/PIL decode path: the file was opened but decoding raised TypeError (cv2 raises TypeError when handed None/invalid buffer rather than a clean cv2 error). Faceswap logs the message and re-raises TypeError only if raise_error=True, otherwise returns None and marks success=False.

Source

Thrown at lib/gui/theme.py:490

        """ Return a background color with a "v" arrow in foreground color

        Parameters
        ----------
        dimensions: tuple
            The (`width`, `height`) of the desired tk image
        thickness: int
            The thickness of the pattern to be drawn
        direction: ["left", "up", "right", "down"]
            The direction that the pattern should be facing

        Returns
        -------
        :class:`numpy.ndarray`
            A 2D, UINT8 array of shape (height, width) of all zeros
        """
        square_size = min(dimensions[1], dimensions[0])
        if square_size < 16 or any(dim % 2 != 0 for dim in dimensions):
            raise FaceswapError("For arrow image, the minimum size across any axis must be 8 and "
                                "dimensions must all be divisible by 2")
        crop_size = (square_size // 16) * 16
        draw_rows = int(6 * crop_size / 16)
        start_row = dimensions[1] // 2 - draw_rows // 2
        initial_indent = 2 * (crop_size // 16) + (dimensions[0] - crop_size) // 2

        retval = np.zeros((dimensions[1], dimensions[0]), dtype="uint8")
        for i in range(start_row, start_row + draw_rows):
            indent = initial_indent + i - start_row
            join = (min(indent + thickness, dimensions[0] // 2),
                    max(dimensions[0] - indent - thickness, dimensions[0] // 2))
            retval[i, np.r_[indent:join[0], join[1]:dimensions[0] - indent]] = 1
        if direction in ("right", "left"):
            retval = np.rot90(retval)
        if direction in ("up", "left"):
            retval = np.flip(retval)
        return retval

View on GitHub (pinned to f530cb7508)

Solutions

Verify the file outside Faceswap: file integrity, non-zero size, `cv2.imread` in a scratch script
Re-download or re-extract the offending image; remove zero-byte files (find . -size 0 -delete after review)
Pass raise_error=False and check the None return to skip bad frames instead of aborting

Example fix

# before
img = read_image("frame_000001.png", raise_error=True)  # TypeError on corrupt file

# after
img = read_image("frame_000001.png", raise_error=False)
if img is None:
    logger.warning("skipping unreadable frame")
    continue

Defensive patterns

Strategy: fallback

Validate before calling

import os

def readable_image(path):
    return os.path.isfile(path) and os.path.getsize(path) > 0

# skip empty/corrupt candidates before read_image

Type guard

def likely_readable_image(path: str) -> bool:
    """Cheap pre-check: existing, non-empty file."""
    import os
    return os.path.isfile(path) and os.path.getsize(path) > 0

Try / catch

try:
    img = read_image(path, raise_error=True)
except TypeError as err:
    if "Error while reading image (TypeError)" in str(err):
        quarantine(path); img = None
    else:
        raise

Prevention

Prefer raise_error=False in batch pipelines and check for None
Filter zero-byte files before runs: find dir -size 0
Verify downloads completed before feeding extraction

When it happens

Trigger: read_image(filename, raise_error=True) where the bytes read from disk are not a decodable image (zero-length file, HTML error page saved as .png, truncated download); or with_metadata=True on a non-PNG file where PNG header parsing gets None values.

Common situations: Partially downloaded/corrupted images in an extraction folder; a file being written concurrently while read; mismatched extension (file named .png but contains JPEG data combined with metadata parsing); filesystem returning empty reads on network mounts.

Related errors

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