トラブルシューティング

症状は、インストールからエクスポートまでの経路上で現れる場所ごとにグループ化され、新規ユーザーに最も多い失敗を先頭に置いています。各項目は原因と修正コマンドを示します。

🚧 インストールと環境

`uv sync` が失敗する

原因: Python 3.12 以降が PATH にないか、uv が見つかりません。 修正: Python のバージョンを確認してから再実行してください:

uv sync --all-extras --group dev

uv が見つからない場合は、Astral の公式パッケージ手順に従ってインストールし、新しいシェルを開いてコマンドを再実行してください。

インストーラーが前提条件の不足を報告する

原因: インストールスクリプトには PATH 上の git と uv が必要です。 修正: 指定された前提条件をインストールし、同じインストールコマンドを再実行してください。チェックアウトを既定のユーザーデータディレクトリの外に置くべき場合は、再実行前に DISPATCHATLAS_HOME を設定してください。

更新が変更を報告するが適用しない

原因: 更新チェックは既定で読み取り専用です。 修正: DISPATCHATLAS_REF をリリースタグまたは 40 文字のフルコミット SHA に設定し、デタッチドチェックアウトによる更新を明示的に適用してください:

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

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

アンインストールが対象を拒否する

原因: アンインストールスクリプトは、空のパス、ファイルシステムのルート、ホームディレクトリ、そして DispatchAtlas ワークスペースのセンチネルを持たないディレクトリを拒否します。 修正: DISPATCHATLAS_HOME をインストール済みチェックアウトのパスに設定し、アンインストールコマンドを再実行してください。

📦 インポート

`ModuleNotFoundError: No module named 'dispatchatlas'`

原因: ワークスペースが同期されていないか、スクリプトがプロジェクト環境外の Python インタープリタの下で実行されています。 修正: リポジトリのルートから、プロジェクト環境が有効になるよう uv 経由で同期しスクリプトを実行してください:

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

ソルバー作成時の `MissingOptionalDependencyError`

原因: オプションの重量級バックエンド（厳密解ソルバー、学習推定器）はエクストラの背後に留まり、実行時に探索されます。パッケージのインポート時にインポートされることはありません。エラーは不足しているエクストラ、その目的、そしてライセンス注記を示します。 修正: 指定されたエクストラ（例: exact、exact-commercial、learning）をインストールするか、バックエンドが存在するソルバーを選択してください。ソルバーの依存関係宣言はソルバーシステムに列挙されています。

🧪 キャンペーンの構成と実行

キャンペーン検証時の `CampaignConfigError`

原因: 構成フィールドが検証に失敗しています——空の id、非正のシードまたは予算、重複する停止プロトコル名、あるいは空のベンチマーク・ソルバー・目的のリスト。エラーは失敗したフィールドパスを保持します。 修正: 指定されたフィールドを修正してください。キャンペーンエンジンページがすべての構成ブロックを文書化しており、experiments/configs/smoke-pilot.json は完全な動作例です:

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

ベンチマーク問題取得時の `KeyError`

原因: 問題 id がプロバイダのカタログにないか、ProblemId が期待される箇所に素の文字列が渡されました。 修正: id を包み（provider.get_problem(ProblemId("smoke-job-shop-0"))）、まず provider.list_problem_ids() で利用可能な id を一覧してください——チュートリアルを参照。

完全キャンペーンが実行を拒否する

原因: full ステージのキャンペーンは、その承認が構成に記録されるまで、 full-campaign execution requires statistical design approval でフェイルクローズします。 修正: ローカル確認には smoke または pilot ステージで実行するか、完全実行を有効化する前にリリース準備状況に従って統計設計の承認を記録してください。

再開が完了済みの実行をスキップせず再計画する

原因: .checkpoints/{campaign_id}.json のチェックポイントは構成ハッシュで守られており、構成のいかなる変更も、静かに再利用するのではなく無効化します。 修正: 再開するには構成を変更しないままにするか、変更後の構成の下で新しい計画を受け入れてください。ワークスペース契約は再現可能なキャンペーンに記述されています。

📤 エクスポート、レポート、サイト

分析エクスポートがチェックポイントの欠如を報告する

原因: dispatchatlas export コマンドは、checkpoint.json、plan.json、 environment.json、および結果記録を備えた完了済みキャンペーンディレクトリを期待します。 修正: --campaign-dir を親ではなくキャンペーン結果ディレクトリに向けるか、キャンペーンを再実行してください:

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

--target-dir が現在の作業ディレクトリの外にある場合は、宛先を含む明示的な --authorized-output-root を渡してください。

ポータルデータの検証が失敗する

原因: 静的サイトのアセットがポータル結果エクスポートと足並みが揃っていません。 修正: 静的アセットを再生成してください。コマンドは既定でコミット済みの開示フィルタ済み結果エクスポート exports/portal-results.json を読むため、引数なしで実行されます:

uv run python tools/build_site_assets.py

別の開示フィルタ済み portal-results.json エクスポートを公開するには --result-source を渡してください:

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

コマンドが dispatchatlas site-assets: error を報告する場合は、--result-source （または既定の exports/portal-results.json）が、分析エクスポート経路で生成された既存の portal-results.json ファイルを指していることを確認してください。

ポータルの秘匿ゲートが失敗する

原因: 公開面に属さないトークンがポータルデータに到達したため、公開される面が汎用のスケジューリング最適化ツールキットとして読まれるよう、ビルドはフェイルクローズします。 修正: エラーは違反する各成果物、フィールドパス、トークンを列挙します。その成果物を出力するビルダー（tools/portal_contract.py またはそのソースエビデンスの下）で違反するフィールドを秘匿し、公開安全な派生エビデンスのみがポータルデータに到達するようにして、再生成してください:

uv run python tools/build_site_assets.py

この失敗はポータルエクスポートの欠如とは異なります。別の --result-source を渡しても解消されません——違反トークンはその発生源で除去する必要があります。

サイトビルドがページを見つけられない

修正: サイト契約テストとドキュメントビルドを実行してください:

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

あるソルバーが推奨から欠落している

原因: 選択はメタデータでフィルタリングします。 修正: ソルバーのメタデータで、目的のサポート、必要な能力タグ、オプション依存関係の状態、そしてエビデンス層の可視性を確認してください——ソルバーシステム。

まだ解決しませんか？ FAQを参照するか、 GitHub リポジトリで issue を開いてください。