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

Start with the layer at which the failure occurs. A missing DAT path is not an
instrument error; a missing native GPIB library cannot be fixed by changing
the measurement loop.

Configuration cannot be found
-----------------------------

Typical symptoms are missing DOT, INI, or DAT files and driver names that
cannot be imported.

#. Derive absolute ``SearchPaths`` from the directory of the ``conf.py``.
#. Check that the DOT node refers to the expected INI file.
#. Check ``driver`` and ``type`` in the INI file.
#. Run the virtual configuration through the same script.

Paths should not depend on the accidental working directory. The
:doc:`../configuration/workflow` page shows a robust directory structure. For
parser errors or unclear units, see the :doc:`INI and DAT reference
<../configuration/instrument-data>`.

Invalid DOT condition or signal path
------------------------------------

``ConditionContextError`` usually means that a DOT variable was not provided
through ``condition_map`` and the explicit context.
``GraphValidationError`` can indicate missing device nodes, invalid
references, or paths that are not uniquely active.

Evaluate conditions without device actions first:

.. code-block:: python

   graph.EvaluateConditions(
       doAction=False,
       context={"frequency": 100e6},
   )

Then use ``check_paths`` or ``mpylab-dot-migrate --check`` across the complete
intended frequency range. Exactly one active path is the normal case.
Parallel active paths are valid only when the application explicitly supports
them. The :doc:`DOT reference <../configuration/dot>` explains context
mapping, boundary validation, and safe actions together.

VISA or GPIB instrument cannot be opened
----------------------------------------

The message

.. code-block:: text

   gpib_ctypes is installed but could not locate the gpib library

means that the Python package is present but no suitable native GPIB library
could be loaded. Another ``pip install`` is not sufficient. Install or
configure the operating-system or vendor driver, then inspect the backends
recognized by PyVISA:

.. code-block:: console

   pyvisa-info

Also check:

* whether the VISA resource address in the INI file is correct;
* whether another process owns or locks the instrument;
* whether the selected backend matches the installed library;
* whether the same graph works with virtual instruments.

For Prologix connections, host, port, and GPIB address in the resource string
must also be correct. Increase communication timeouts only after confirming
that the instrument actually received the command.

The measurement appears to hang
-------------------------------

Long initialization, a sweep, or a detector with a long hold time may be
working correctly without returning a value immediately. Inspect the log and
instrument state first. An application should announce long phases before
they start and provide aggregated progress during scans.

In a Qt application, blocking instrument calls must run in a worker. When the
event loop is blocked, Stop and RF-off cannot be operated reliably either.
See :doc:`../framework/ui-workers`.

Autosave does not resume
------------------------

Check:

#. Does ``autosave_filename`` resolve to the same file after restart?
#. Is the same measurement script started with a compatible configuration?
#. Does the log show a resume prompt or a load error?
#. Is the file complete and readable by the process?
#. Do ``measurement`` and ``method`` in ``autosave_resume`` match the script?

Use ``load_pickle_compat`` to load pickles in application code. A successful
resume test must additionally prove that completed measurement points are not
visited again.

Pickle log file belongs to another computer
-------------------------------------------

When loading, mpylab first tries to reopen the original log file. If its path
is unavailable, it creates ``restored-<name>.log`` in the current working
directory and records the relocation there. Inspect ``logfile_restore_status``
and ``logfile_restore_message`` on the loaded measurement object if the new
destination is unclear.

Qt tests fail during CI collection
----------------------------------

For headless tests, set:

.. code-block:: console

   QT_QPA_PLATFORM=offscreen python -m pytest test

``offscreen`` does not replace missing native Qt libraries. Errors mentioning
``libxkbcommon.so.0``, ``libGL.so.1``, or ``libEGL.so.1`` require the
corresponding operating-system packages on the CI host. Continue to run the
Qt tests after installing them instead of skipping the tests globally.

Documentation build fails
-------------------------

Use the same strict options locally as the pipeline:

.. code-block:: console

   sphinx-build -W --keep-going -E -a \
       -b html docs/next/source docs/next/build/html

``dot command 'dot' cannot be run`` indicates that Graphviz is missing, not
the Python package ``pydot``. Deprecation warnings from
``pydot.dot_parser`` about Pyparsing methods originate in the dependency.
Monitor them, but do not hide them by changing measurement DOT files.

Initial diagnostic information
------------------------------

Record at least the following for a reproducible problem report:

* mpylab, SCUQ, and Python versions;
* operating system and VISA backend;
* script and ``conf.py``;
* last complete log lines;
* affected frequency, level, or position range;
* whether the corresponding virtual run succeeds.

Credentials, tokens, and confidential instrument addresses do not belong in
logs or issue reports.