Dépannage

Les symptômes sont regroupés selon l'endroit où ils apparaissent sur le chemin de l'installation à l'export, les pannes les plus courantes des nouveaux venus en premier. Chaque entrée nomme la cause et la commande de correction.

🚧 Installation et environnement

uv sync échoue

Cause : Python 3.12 ou plus récent n'est pas dans le PATH, ou uv est absent. Correction : Confirmez la version de Python, puis relancez :

uv sync --all-extras --group dev

Si uv est absent, installez-le depuis les instructions officielles du paquet Astral, ouvrez un nouveau shell et relancez la commande.

L'installateur signale un prérequis manquant

Cause : Les scripts d'installation requièrent git et uv dans le PATH. Correction : Installez le prérequis nommé, puis relancez la même commande d'installation. Définissez DISPATCHATLAS_HOME avant de relancer lorsque le checkout doit résider hors du répertoire de données utilisateur par défaut.

La mise à jour signale des changements mais ne les applique pas

Cause : Les vérifications de mise à jour sont en lecture seule par défaut. Correction : Définissez DISPATCHATLAS_REF sur une étiquette de version ou un SHA de commit complet de 40 caractères, puis appliquez explicitement la mise à jour par checkout détaché :

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

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

La désinstallation refuse une cible

Cause : Les scripts de désinstallation refusent les chemins vides, les racines du système de fichiers, les répertoires personnels et les répertoires sans la sentinelle de l'espace de travail DispatchAtlas. Correction : Définissez DISPATCHATLAS_HOME sur le chemin du checkout installé et relancez la commande de désinstallation.

📦 Imports

ModuleNotFoundError: No module named 'dispatchatlas'

Cause : L'espace de travail n'est pas synchronisé, ou le script s'exécute sous un interpréteur Python hors de l'environnement du projet. Correction : Depuis la racine du dépôt, synchronisez et exécutez les scripts via uv pour que l'environnement du projet soit actif :

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

MissingOptionalDependencyError lors de la création d'un solveur

Cause : Les backends lourds optionnels (solveurs exacts, estimateurs d'apprentissage) restent derrière des extras et sont sondés à l'exécution, jamais importés lors de l'import du paquet. L'erreur nomme l'extra manquant, son objet et toute note de licence. Correction : Installez l'extra nommé (par exemple exact, exact-commercial, ou learning) ou sélectionnez un solveur dont le backend est présent. Les déclarations de dépendances des solveurs sont listées dans le système de solveurs.

🧪 Configuration et exécution de campagnes

CampaignConfigError lors de la validation d'une campagne

Cause : Un champ de configuration échoue à la validation — un id vide, une graine ou un budget non positifs, des noms de protocole d'arrêt en double, ou une liste vide de benchmarks, de solveurs ou d'objectifs. L'erreur porte le chemin du champ défaillant. Correction : Corrigez le champ nommé. La page du moteur de campagnes documente chaque bloc de configuration, et experiments/configs/smoke-pilot.json est un exemple de travail complet :

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

KeyError lors de la récupération d'un problème de benchmark

Cause : L'id du problème n'est pas dans le catalogue du fournisseur, ou une simple chaîne a été passée là où un ProblemId est attendu. Correction : Enveloppez l'id (provider.get_problem(ProblemId("smoke-job-shop-0"))) et listez d'abord les ids disponibles avec provider.list_problem_ids() — voir les tutoriels.

La campagne complète refuse de s'exécuter

Cause : Une campagne à l'étape full échoue en position fermée avec full-campaign execution requires statistical design approval jusqu'à ce que cette approbation soit enregistrée sur la configuration. Correction : Exécutez à l'étape smoke ou pilot pour les vérifications locales, ou enregistrez l'approbation du plan statistique selon préparation de la version avant d'activer l'exécution complète.

La reprise replanifie au lieu de sauter les exécutions terminées

Cause : Le point de contrôle dans .checkpoints/{campaign_id}.json est protégé par un hash de configuration ; tout changement de configuration l'invalide au lieu de le réutiliser silencieusement. Correction : Gardez la configuration inchangée pour reprendre, ou acceptez un nouveau plan sous la configuration modifiée. Le contrat de l'espace de travail est décrit dans campagnes reproductibles.

📤 Exports, rapports et le site

L'export d'analyse signale un point de contrôle manquant

Cause : La commande dispatchatlas export attend un répertoire de campagne terminé avec checkpoint.json, plan.json, environment.json et les enregistrements de résultats. Correction : Pointez --campaign-dir sur le répertoire de résultats de la campagne plutôt que sur son parent, ou relancez la campagne :

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

Si --target-dir est hors du répertoire de travail actuel, passez un --authorized-output-root explicite qui contient la destination.

La validation des données du portail échoue

Cause : Les actifs du site statique sont désynchronisés de l'export des résultats du portail. Correction : Régénérez les actifs statiques. La commande lit par défaut l'export de résultats filtré par divulgation et validé dans exports/portal-results.json, elle s'exécute donc sans argument :

uv run python tools/build_site_assets.py

Passez --result-source pour publier un export portal-results.json filtré par divulgation différent :

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

Si la commande signale dispatchatlas site-assets: error, vérifiez que --result-source (ou le exports/portal-results.json par défaut) pointe sur un fichier portal-results.json existant généré par le chemin d'export d'analyse.

La porte de caviardage du portail échoue

Cause : Un jeton qui n'a pas sa place sur la surface publique a atteint les données du portail, donc la compilation échoue en position fermée pour que la face publiée se lise comme une boîte à outils générique d'optimisation d'ordonnancement. Correction : L'erreur liste chaque artefact fautif, chemin de champ et jeton. Caviardez le champ fautif dans le constructeur qui émet cet artefact (sous tools/portal_contract.py ou sa preuve source) afin que seule une preuve dérivée sûre pour le public atteigne les données du portail, puis régénérez :

uv run python tools/build_site_assets.py

Cette panne diffère d'un export de portail manquant : passer un --result-source différent ne la résout pas — le jeton fautif doit être supprimé à sa source.

La compilation du site ne trouve pas une page

Correction : Exécutez les tests de contrat du site et la compilation de la documentation :

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

Un solveur manque dans les recommandations

Cause : La sélection filtre sur les métadonnées. Correction : Vérifiez dans les métadonnées du solveur la prise en charge des objectifs, les étiquettes de capacité requises, l'état des dépendances optionnelles et la visibilité par niveau de preuve dans système de solveurs.

Toujours bloqué ? Voir la FAQ ou ouvrez un ticket sur le dépôt GitHub.