समस्या-निवारण

लक्षणों को इस आधार पर समूहित किया गया है कि वे इंस्टॉल से निर्यात तक के मार्ग पर कहाँ प्रकट होते हैं, सबसे आम नवागंतुक विफलताएँ पहले। प्रत्येक प्रविष्टि कारण और सुधार कमांड का नाम देती है।

🚧 इंस्टॉल और परिवेश

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

कारण: वैकल्पिक भारी बैकएंड (सटीक सॉल्वर, अधिगम आकलक) extras के पीछे रहते हैं और रनटाइम पर जाँचे जाते हैं, पैकेज इम्पोर्ट के दौरान कभी इम्पोर्ट नहीं होते। त्रुटि अनुपस्थित extra, उसका प्रयोजन, और कोई भी लाइसेंस नोट बताती है। सुधार: नामित extra इंस्टॉल करें (उदाहरण के लिए 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

कोई सॉल्वर अनुशंसाओं से अनुपस्थित है

कारण: चयन मेटाडेटा पर फ़िल्टर करता है। सुधार: सॉल्वर के मेटाडेटा में उद्देश्य समर्थन, आवश्यक क्षमता टैग, वैकल्पिक निर्भरता स्थिति, और प्रमाण-स्तर दृश्यता जाँचें — सॉल्वर सिस्टम।

अब भी अटके हैं? सामान्य प्रश्न देखें या GitHub रिपॉज़िटरी पर एक issue खोलें।