deepfakes/faceswap · error · ValueError

Metadata is only supported for .png and .tif images

Error message

Metadata is only supported for .png and .tif images

What it means

encode_image only supports embedding metadata (alignments, training info) in PNG and TIFF containers, because only those have writers (png_write_meta / tiff_write_meta). Passing a truthy metadata argument together with any other extension (e.g. .jpg, .webp) raises this ValueError before encoding.

Source

Thrown at lib/image.py:456

        Any encoding arguments to pass to cv2's imencode function
    metadata
        Metadata for the image. If provided, and the extension is png or tiff, this information
        will be written to the PNG itxt header. Default:``None`` Can be provided as a python dict
        or pre-encoded

    Returns
    -------
    encoded_image: bytes
        The image encoded into the correct file format as bytes

    Example
    -------
    >>> image_file = "/path/to/image.png"
    >>> image = read_image(image_file)
    >>> encoded_image = encode_image(image, ".jpg")
    """
    if metadata and extension.lower() not in (".png", ".tif"):
        raise ValueError("Metadata is only supported for .png and .tif images")
    args = tuple() if encoding_args is None else encoding_args

    retval = cv2.imencode(extension, image, args)[1].tobytes()
    if metadata:
        func = {".png": png_write_meta, ".tif": tiff_write_meta}[extension]
        retval = func(retval, metadata)
    return retval


def png_write_meta(image: bytes, data: PNGHeader | dict[str, T.Any] | bytes) -> bytes:
    """Write Faceswap information to a png's iTXt field.

    Parameters
    ----------
    image
        The bytes encoded png file to write header data to
    data
        The dictionary to write to the header. Can be pre-encoded as utf-8.

View on GitHub (pinned to f530cb7508)

Solutions

1. Switch the output extension to '.png' (or '.tif') when metadata is required.
2. Or stop passing metadata (set it to None/omit) if a lossy format like .jpg is desired.
3. Check the plugin/config option that controls output format (GUI: extract settings; CLI: config .ini) and set it to png.

Example fix

# before
encoded = encode_image(image, '.jpg', metadata=meta)  # ValueError

# after
encoded = encode_image(image, '.png', metadata=meta)

def encode_with_meta(image, extension, metadata):
    if metadata and extension.lower() not in ('.png', '.tif'):
        extension = '.png'  # or raise early with your own message
    return encode_image(image, extension, metadata=metadata)

try:
    encoded = encode_image(image, ext, metadata=meta)
except ValueError:
    encoded = encode_image(image, '.png', metadata=meta)  # fall back to png

When it happens

Trigger: Calling encode_image(image, '.jpg', metadata=alignments) or configuring an output format of jpeg while a pipeline stage (e.g. extraction with aligned-face metadata) tries to persist metadata.

Common situations: User changes output format to .jpg in extract/train settings while metadata writing is enabled; scripts that pass extension as 'jpg' instead of '.jpg' path is different — here it is format choice that conflicts.

Related errors

• No display detected. GUI mode has been disabled.
• Config file does not exist at: {ini_path}
• [{self._name}] List values should be set as a Str or List. G
• [{self._name}] Expected {self.datatype} got {type(value)} ({
• Invalid header found in png: {filename}

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