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

.. _troubleshooting:

Use this page when installation or tool execution fails.

General checks
--------------

#. On Windows, if installation fails in Git Bash, retry from CMD or PowerShell.
#. Run install commands in verbose mode when you need detailed failure output::

        pip install --verbose ...

#. If the build process appears to crash, verify that your machine has enough RAM.

Conan/mpfr download timeout
---------------------------

If downloading mpfr from gnu.org times out, edit:

::

    C:\Users\<User name>\.conan\data\mpfr\4.1.0\_\_\export\conandata.yml

Replace:

``https://ftp.gnu.org/gnu/mpfr/mpfr-4.1.0.tar.gz``

with:

``https://www.mpfr.org/mpfr-4.1.0/mpfr-4.1.0.tar.gz``

Reset Conan cache
-----------------

If installation state appears corrupted, remove Conan cache directories and reinstall.

Typical locations:

::

    C:\
    C:\Users\<User name>\

Wayland warning on Linux
------------------------

If running GUI tools shows a Wayland warning, set this variable before launching tools:

.. code-block:: bash

    export QT_QPA_PLATFORM=wayland

Git not found on Windows
------------------------

If ``pip`` cannot find Git from CMD, make sure PATH includes:

``C:\Program Files\Git\cmd``

Conan network timeout setting
-----------------------------

For repeated network timeouts in Conan downloads, increase the timeout:

.. code-block:: bash

    mkdir -p ~/.conan2
    echo "core.net.http:timeout=600" >> ~/.conan2/global.conf