{"record":{"id":"42e84146a7f8cbbb","repo":"deepfakes/faceswap","slug":"failed-to-load-image-filename-original-error","errorCode":null,"errorMessage":"Failed to load image '{filename}'. Original Error: {str(err)}","messagePattern":"Failed to load image '(.+?)'\\. Original Error: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"lib/image.py","lineNumber":150,"sourceCode":"        msg = f\"Error while reading image (TypeError): '{filename}'\"\n        msg += f\". Original error message: {str(err)}\"\n        logger.error(msg)\n        if raise_error:\n            raise TypeError(msg) from err\n    except ValueError as err:\n        success = False\n        msg = (\"Error while reading image. This can be caused by special characters in the \"\n               f\"filename or a corrupt image file: '{filename}'\")\n        msg += f\". Original error message: {str(err)}\"\n        logger.error(msg)\n        if raise_error:\n            raise ValueError(msg) from err\n    except Exception as err:  # pylint:disable=broad-except\n        success = False\n        msg = f\"Failed to load image '{filename}'. Original Error: {str(err)}\"\n        logger.error(msg)\n        if raise_error:\n            raise Exception(msg) from err  # pylint:disable=broad-exception-raised\n    logger.trace(\"Loaded image: '%s'. Success: %s\", filename, success)  # type:ignore[attr-defined]\n    return retval\n\n\n@T.overload\ndef read_image_batch(filenames: list[str], with_metadata: T.Literal[False] = False\n                     ) -> np.ndarray: ...\n\n\n@T.overload\ndef read_image_batch(filenames: list[str], with_metadata: T.Literal[True]\n                     ) -> tuple[np.ndarray, list[PNGHeader]]: ...\n\n\ndef read_image_batch(filenames: list[str], with_metadata: bool = False\n                     ) -> np.ndarray | tuple[np.ndarray, list[PNGHeader]]:\n    \"\"\"Load a batch of images from the given file locations.\n","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/lib/image.py#L132-L168","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the logged 'Original Error' to classify the cause (IO vs permission vs decode) and fix that root cause","For batch processing pass raise_error=False and skip/log the None returns so one bad frame does not abort a long job","Pre-flight check each file: os.access(path, os.R_OK) and non-zero size before adding it to the batch"],"exampleFix":"# before\nimgs = [read_image(f, raise_error=True) for f in files]  # one OSError kills the batch\n\n# after\nimgs, skipped = [], []\nfor f in files:\n    if not (os.path.isfile(f) and os.access(f, os.R_OK) and os.path.getsize(f) > 0):\n        skipped.append(f)\n        continue\n    im = read_image(f, raise_error=False)\n    if im is None:\n        skipped.append(f)\n    else:\n        imgs.append(im)","handlingStrategy":"fallback","validationCode":"import os\n\ndef preflight_image(path):\n    return (os.path.isfile(path)\n            and os.access(path, os.R_OK)\n            and os.path.getsize(path) > 0)\n\nbatch = [f for f in files if preflight_image(f)]","typeGuard":"def safe_to_read(path: str) -> bool:\n    \"\"\"True when path exists, is readable and non-empty.\"\"\"\n    import os\n    try:\n        return os.path.isfile(path) and os.access(path, os.R_OK) and os.path.getsize(path) > 0\n    except OSError:\n        return False","tryCatchPattern":"imgs = []\nfor f in files:\n    img = read_image(f, raise_error=False)\n    if img is None:\n        logger.warning(\"skipping unreadable frame: %s\", f)\n        continue\n    imgs.append(img)","preventionTips":["Use raise_error=False plus None-checks for resilience in batch jobs","Pre-check os.access/getsize on network or shared filesystems","Log and quarantine unreadable files instead of aborting long runs"],"tags":["faceswap","image-io","robustness","io","batch"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}