Fehlersuche¶

Beginnen Sie mit der Ebene, auf der der Fehler auftritt. Ein nicht gefundener DAT-Pfad ist kein Gerätefehler; eine fehlende native GPIB-Bibliothek lässt sich nicht durch Änderung der Messschleife beheben.

Konfiguration wird nicht gefunden¶

Typische Symptome sind nicht gefundene DOT-, INI- oder DAT-Dateien und Treibernamen, die nicht importiert werden können.

Geben Sie der conf.py absolute, aus ihrem eigenen Verzeichnis abgeleitete SearchPaths.
Prüfen Sie, ob der DOT-Knoten auf den erwarteten INI-Dateinamen zeigt.
Prüfen Sie driver und type in der INI-Datei.
Starten Sie die virtuelle Konfiguration aus demselben Skript.

Pfade sollten nicht vom zufälligen Arbeitsverzeichnis abhängen. Das Ablaufkonfiguration mit conf.py zeigt eine robuste Verzeichnisstruktur. Bei Parserfehlern oder unklaren Einheiten hilft die INI- und DAT-Referenz.

DOT-Condition oder Signalpfad ist ungültig¶

ConditionContextError bedeutet meist, dass eine DOT-Variable nicht über condition_map und den expliziten Kontext bereitgestellt wurde. GraphValidationError weist unter anderem auf fehlende Geräteknoten, ungültige Referenzen oder nicht eindeutig aktive Pfade hin.

Prüfen Sie Conditions zunächst ohne Geräteaktionen:

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

Nutzen Sie anschließend check_paths oder das mpylab-dot-migrate --check-Werkzeug über den vollständigen vorgesehenen Frequenzbereich. Genau ein aktiver Pfad ist der Normalfall. Parallele aktive Pfade sind nur zulässig, wenn die Anwendung sie ausdrücklich unterstützt. Die DOT-Referenz erläutert Kontext-Mapping, Grenzwertprüfung und sichere Actions zusammenhängend.

VISA- oder GPIB-Gerät lässt sich nicht öffnen¶

Die Meldung

gpib_ctypes is installed but could not locate the gpib library

bedeutet, dass das Python-Paket vorhanden ist, aber keine passende native GPIB-Bibliothek geladen werden konnte. Ein weiteres pip install genügt hier nicht. Installieren oder konfigurieren Sie den System- beziehungsweise Herstellertreiber und prüfen Sie anschließend die von PyVISA erkannten Backends:

pyvisa-info

Prüfen Sie außerdem:

stimmt die VISA-Ressourcenadresse in der INI-Datei;
ist das Gerät mit einem anderen Prozess verbunden oder gesperrt;
passt das ausgewählte Backend zur installierten Bibliothek;
funktioniert derselbe Graph mit virtuellen Geräten.

Bei Prologix-Verbindungen müssen zusätzlich Host, Port und GPIB-Adresse in der Ressourcenangabe stimmen. Kommunikationstimeouts sollten erst vergrößert werden, wenn feststeht, dass das Gerät den Befehl tatsächlich erhalten hat.

Die Messung scheint zu hängen¶

Lange Initialisierung, ein Sweep oder ein Detektor mit langer Haltezeit kann korrekt arbeiten, ohne sofort einen Messwert zurückzugeben. Prüfen Sie zuerst Log und Gerätestatus. Eine Anwendung sollte vor langen Phasen den nächsten Schritt protokollieren und während Scans gebündelten Fortschritt melden.

In einer Qt-Anwendung müssen blockierende Geräteaufrufe in einem Worker laufen. Dreht sich die Ereignisschleife nicht mehr, kann auch Stop oder RF-Off nicht zuverlässig bedient werden. Siehe UI-Adapter und Worker-Schnittstelle.

Autosave wird nicht fortgesetzt¶

Prüfen Sie:

Zeigt autosave_filename beim Neustart auf dieselbe Datei?
Wird dasselbe Messskript mit einer kompatiblen Konfiguration gestartet?
Enthält das Log eine angebotene Resume-Entscheidung oder einen Ladefehler?
Ist die Datei vollständig und für den Prozess lesbar?
Stimmen measurement und method in autosave_resume mit dem Skript überein?

Laden Sie Pickles im Anwendungscode mit load_pickle_compat. Ein erfolgreicher Resume-Test muss zusätzlich zeigen, dass abgeschlossene Messpunkte nicht erneut angefahren werden.

Logdatei eines Pickles liegt auf einem anderen Rechner¶

Beim Laden versucht mpylab zunächst, die ursprüngliche Logdatei wieder zu öffnen. Ist ihr Pfad nicht verfügbar, wird im aktuellen Arbeitsverzeichnis eine Datei restored-<name>.log angelegt und darin auf die Verlagerung hingewiesen. Prüfen Sie logfile_restore_status und logfile_restore_message am geladenen Messobjekt, wenn die neue Ablage unklar ist.

Qt-Tests schlagen in CI vor der Testausführung fehl¶

Für headless Tests setzen Sie:

QT_QPA_PLATFORM=offscreen python -m pytest test

offscreen ersetzt jedoch keine fehlenden nativen Qt-Bibliotheken. Fehler wie libxkbcommon.so.0, libGL.so.1 oder libEGL.so.1 erfordern die entsprechenden Systempakete des CI-Rechners. Die Qt-Tests sollten danach weiterhin ausgeführt und nicht pauschal übersprungen werden.

Dokumentations-Build schlägt fehl¶

Bauen Sie lokal mit denselben strengen Optionen wie die Pipeline:

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

dot command 'dot' cannot be run verweist auf eine fehlende Graphviz-Installation, nicht auf das Python-Paket pydot. Warnungen aus pydot.dot_parser zu veralteten Pyparsing-Methoden stammen aus der Abhängigkeit. Sie sollten beobachtet, aber nicht durch Änderungen an Mess-DOT-Dateien kaschiert werden.

Erste Diagnoseinformationen¶

Für eine reproduzierbare Fehlermeldung halten Sie mindestens fest:

mpylab-, SCUQ- und Python-Version;
Betriebssystem und verwendetes VISA-Backend;
Skript und conf.py;
letzte vollständige Logzeilen;
betroffener Frequenz-, Pegel- oder Positionsbereich;
ob der entsprechende virtuelle Lauf erfolgreich ist.

Zugangsdaten, Tokens und vertrauliche Geräteadressen gehören nicht in Logs oder Fehlermeldungen.