Troubleshooting
===============================================

Bug Reports
--------------------------------------------------------------

You can submit a bug report using `GitHub Issues <https://github.com/JacobDev1/xl-converter/issues>`_.

Common Problems
-----------------------------------------------

**Some TIFF images fail to convert (single page).**
    Problems with TIFF images are normal. The image is either not up to the specification, incompatible or corrupted.

    You can fix non-compliant TIFF images with ``tiffcp``. Install ``libtiff-tools`` with your package manager. Example: ``tiffcp input.tif output.tif``.

    .. note::
        
        Multipage TIFF images and some compression algorithms are not supported.

**Lossless JPEG Transcoding fails on some JPEG images.**
    Answered :ref:`here <lossless-jpeg-transcoding-common-problems>`.

**Encoding JPEG XL is slow / takes up too much RAM.**
    Use settings with low RAM consumption.

    Settings with minimal RAM usage and fast encoding:

    * Lossy (VarDCT) - Effort 1 - 7.
    * Lossless (Modular) - Effort 1 - 9.

    Settings with high RAM usage and slow encoding:

    * Lossy (VarDCT) - Effort 8 - 10.
    * Lossy (Modular).

**This program fails to read an image, but my image viewer can open it fine.**
    Image viewers are a poor metric for verifying image integrity. They will often open slightly corrupted or out of spec images. Problems usually occur during transcoding, where image integrity is crucial.

**Setting a network disk as output causes problems.**
    This application is not designed to use networking storage as an output location. It performs many transformations on images in the output directory.

**Image fails to process correctly if it has no extension / an incorrect extension.**
    This program requires the file extension to match its file type. You can use ``identify`` from ImageMagick to check the type of an image.

**Metadata is not getting preserved when converting to JPEG XL.**
    Answered :ref:`here <metadata-common-pitfalls>`.

**Rotation / Orientation of a converted image is wrong.**
    Answered :ref:`here <metadata-common-pitfalls>`.

**Metadata is not getting preserved when converting from TIFF.**
    Answered :ref:`here <metadata-common-pitfalls>`.

**How can I troubleshoot tricky problems?**
    Enable logging in the Settings, Advanced category, at the very bottom. This allows you to gain more insight into how the program operates.

    Alternatively, use the ``--debug`` option when launching from a terminal.