문제 해결

증상은 설치에서 내보내기까지의 경로에서 나타나는 위치별로 묶여 있으며, 신규 사용자에게 가장 흔한 실패를 먼저 둡니다. 각 항목은 원인과 해결 명령을 명시합니다.

🚧 설치와 환경

`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