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

``at_runner`` Cannot Be Imported
--------------------------------

Install the Python gRPC client from the pinned public ``at-runner`` tag:

.. code-block:: bash

   python -m pip install "at-runner @ git+https://github.com/jgebbie/at-runner.git@v0.3.0#subdirectory=client/python"

The runtime error includes the same git URL through
``at_py.runner_docker.AT_RUNNER_CLIENT_REQUIREMENT``.

Docker Is Missing
-----------------

Docker mode requires the ``docker`` CLI on ``PATH``. If it is unavailable, use a
remote runner instead:

.. code-block:: python

   from at_py import ATClient

   client = ATClient(target="runner-host:50051", runner_mode="remote")

GHCR Pull Fails
---------------

If pulling ``ghcr.io/jgebbie/at-runner:<tag>`` fails with ``403 Forbidden`` or
``denied``, authenticate Docker to GitHub Container Registry with an account that
can read the package:

.. code-block:: bash

   echo YOUR_GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

For GitHub Actions, grant this repository access to the ``at-runner`` container
package and keep ``permissions: packages: read`` on the integration job.

MAT Helpers Raise ImportError
-----------------------------

Install the MAT extra:

.. code-block:: bash

   python -m pip install -e ".[mat]"

MATLAB v7.3 files are loaded through h5py and can be memory intensive because
large dense arrays are loaded fully into RAM.

Unsupported MAT Types
---------------------

High-level MATLAB types that are not used by supported Acoustics Toolbox
``read_*.m`` paths fail loudly. If a real AT fixture needs one of these types,
add a focused fixture and parser support rather than broad speculative handling.

Docs Build Cannot Find Sphinx
-----------------------------

Install development dependencies first:

.. code-block:: bash

   python -m pip install -e ".[dev]"
   sphinx-build -W -b html docs docs/_build