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.

  1. Derive absolute SearchPaths from the directory of the conf.py.

  2. Check that the DOT node refers to the expected INI file.

  3. Check driver and type in the INI file.

  4. Run the virtual configuration through the same script.

Paths should not depend on the accidental working directory. The Workflow configuration with conf.py page shows a robust directory structure. For parser errors or unclear units, see the INI and DAT reference.

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:

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 DOT reference explains context mapping, boundary validation, and safe actions together.

VISA or GPIB instrument cannot be opened

The message

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:

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 UI adapters and worker interface.

Autosave does not resume

Check:

  1. Does autosave_filename resolve to the same file after restart?

  2. Is the same measurement script started with a compatible configuration?

  3. Does the log show a resume prompt or a load error?

  4. Is the file complete and readable by the process?

  5. 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:

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:

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.