Fehlerbehebung

Die Symptome sind danach gruppiert, wo sie auf dem Weg von der Installation zum Export auftreten, mit den häufigsten Fehlern von Neueinsteigern zuerst. Jeder Eintrag nennt die Ursache und den Behebungsbefehl.

🚧 Installation und Umgebung

uv sync schlägt fehl

Ursache: Python 3.12 oder neuer ist nicht im PATH, oder uv fehlt. Behebung: Bestätige die Python-Version und führe erneut aus:

uv sync --all-extras --group dev

Wenn uv fehlt, installiere es gemäß den offiziellen Paketanweisungen von Astral, öffne eine neue Shell und führe den Befehl erneut aus.

Der Installer meldet eine fehlende Voraussetzung

Ursache: Die Installationsskripte benötigen git und uv im PATH. Behebung: Installiere die genannte Voraussetzung und führe denselben Installationsbefehl erneut aus. Setze DISPATCHATLAS_HOME vor dem erneuten Ausführen, wenn der Checkout außerhalb des standardmäßigen Benutzerdatenverzeichnisses liegen soll.

Das Update meldet Änderungen, wendet sie aber nicht an

Ursache: Update-Prüfungen sind standardmäßig schreibgeschützt. Behebung: Setze DISPATCHATLAS_REF auf ein Release-Tag oder einen vollständigen 40-Zeichen-Commit-SHA und wende dann das Update per abgekoppeltem Checkout explizit an:

$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Apply

export DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply

Die Deinstallation verweigert ein Ziel

Ursache: Die Deinstallationsskripte verweigern leere Pfade, Dateisystemwurzeln, Home-Verzeichnisse und Verzeichnisse ohne die DispatchAtlas-Arbeitsbereich-Sentinel. Behebung: Setze DISPATCHATLAS_HOME auf den installierten Checkout-Pfad und führe den Deinstallationsbefehl erneut aus.

📦 Importe

ModuleNotFoundError: No module named 'dispatchatlas'

Ursache: Der Arbeitsbereich ist nicht synchronisiert, oder das Skript läuft unter einem Python-Interpreter außerhalb der Projektumgebung. Behebung: Synchronisiere von der Repository-Wurzel aus und führe Skripte über uv aus, damit die Projektumgebung aktiv ist:

uv sync --all-extras --group dev
uv run python your-script.py

MissingOptionalDependencyError beim Erstellen eines Solvers

Ursache: Optionale schwere Backends (exakte Solver, Lern-Schätzer) bleiben hinter Extras und werden zur Laufzeit geprüft, niemals beim Paketimport importiert. Der Fehler nennt das fehlende Extra, seinen Zweck und etwaige Lizenzhinweise. Behebung: Installiere das genannte Extra (zum Beispiel exact, exact-commercial oder learning) oder wähle einen Solver, dessen Backend vorhanden ist. Die Abhängigkeitsdeklarationen der Solver sind im Solver-System aufgeführt.

🧪 Kampagnenkonfiguration und -ausführung

CampaignConfigError beim Validieren einer Kampagne

Ursache: Ein Konfigurationsfeld besteht die Validierung nicht — eine leere id, ein nicht-positiver Seed oder ein nicht-positives Budget, doppelte Stopp-Protokollnamen oder eine leere Benchmark-, Solver- oder Zielliste. Der Fehler trägt den Pfad des fehlerhaften Feldes. Behebung: Korrigiere das genannte Feld. Die Seite der Kampagnen-Engine dokumentiert jeden Konfigurationsblock, und experiments/configs/smoke-pilot.json ist ein vollständiges funktionierendes Beispiel:

uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json

KeyError beim Abrufen eines Benchmark-Problems

Ursache: Die Problem-id ist nicht im Katalog des Anbieters, oder eine einfache Zeichenkette wurde übergeben, wo ein ProblemId erwartet wird. Behebung: Umhülle die id (provider.get_problem(ProblemId("smoke-job-shop-0"))) und liste zuerst die verfügbaren ids mit provider.list_problem_ids() auf — siehe die Tutorials.

Die vollständige Kampagne verweigert die Ausführung

Ursache: Eine Kampagne in der Stufe full schlägt schließend mit full-campaign execution requires statistical design approval fehl, bis diese Freigabe in der Konfiguration vermerkt ist. Behebung: Führe in der Stufe smoke oder pilot für lokale Prüfungen aus, oder vermerke die statistische Design-Freigabe gemäß Release-Bereitschaft, bevor du die vollständige Ausführung aktivierst.

Das Fortsetzen plant neu, statt abgeschlossene Läufe zu überspringen

Ursache: Der Prüfpunkt unter .checkpoints/{campaign_id}.json ist durch einen Konfigurations-Hash geschützt; jede Konfigurationsänderung macht ihn ungültig, statt ihn still wiederzuverwenden. Behebung: Halte die Konfiguration unverändert, um fortzusetzen, oder akzeptiere einen frischen Plan unter der geänderten Konfiguration. Der Arbeitsbereich-Vertrag ist in reproduzierbaren Kampagnen beschrieben.

📤 Exporte, Berichte und die Website

Der Analyse-Export meldet einen fehlenden Prüfpunkt

Ursache: Der Befehl dispatchatlas export erwartet ein abgeschlossenes Kampagnenverzeichnis mit checkpoint.json, plan.json, environment.json und Ergebnisdatensätzen. Behebung: Richte --campaign-dir auf das Ergebnisverzeichnis der Kampagne statt auf dessen übergeordnetes Verzeichnis, oder führe die Kampagne erneut aus:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core

Wenn --target-dir außerhalb des aktuellen Arbeitsverzeichnisses liegt, übergib einen expliziten --authorized-output-root, der das Ziel enthält.

Die Validierung der Portaldaten schlägt fehl

Ursache: Die statischen Website-Assets sind nicht mehr mit dem Portal-Ergebnis-Export im Gleichschritt. Behebung: Regeneriere die statischen Assets. Der Befehl liest standardmäßig den committeten, nach Offenlegung gefilterten Ergebnis-Export unter exports/portal-results.json und läuft daher ohne Argumente:

uv run python tools/build_site_assets.py

Übergib --result-source, um einen anderen nach Offenlegung gefilterten portal-results.json-Export zu veröffentlichen:

uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json

Wenn der Befehl dispatchatlas site-assets: error meldet, prüfe, dass --result-source (oder das standardmäßige exports/portal-results.json) auf eine vorhandene portal-results.json-Datei zeigt, die vom Analyse-Export-Pfad erzeugt wurde.

Das Redaktions-Tor des Portals schlägt fehl

Ursache: Ein Token, das nicht auf die öffentliche Oberfläche gehört, hat die Portaldaten erreicht, also schlägt die Build schließend fehl, damit die veröffentlichte Oberfläche als generisches Toolkit zur Scheduling-Optimierung lesbar bleibt. Behebung: Der Fehler listet jedes anstößige Artefakt, jeden Feldpfad und jedes Token auf. Schwärze das anstößige Feld im Builder, der dieses Artefakt ausgibt (unter tools/portal_contract.py oder seiner Quellevidenz), damit nur öffentlich-sichere abgeleitete Belege die Portaldaten erreichen, und regeneriere dann:

uv run python tools/build_site_assets.py

Dieser Fehler unterscheidet sich von einem fehlenden Portal-Export: das Übergeben eines anderen --result-source behebt ihn nicht — das anstößige Token muss an seiner Quelle entfernt werden.

Die Website-Build findet eine Seite nicht

Behebung: Führe die Website-Vertragstests und die Dokumentations-Build aus:

uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check

Ein Solver fehlt in den Empfehlungen

Ursache: Die Auswahl filtert nach Metadaten. Behebung: Prüfe in den Metadaten des Solvers die Zielunterstützung, die erforderlichen Fähigkeits-Tags, den Status optionaler Abhängigkeiten und die Sichtbarkeit nach Belegstufe im Solver-System.

Immer noch festgefahren? Siehe die FAQ oder eröffne ein Issue im GitHub-Repository.