निर्माण विफलताओं का समस्या निवारण

When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…

जब Orbit बिल्ड विफल हो जाता है, तो डिप्लॉयमेंट विवरण पृष्ठ आपको पूरा लॉग, एक वर्गीकृत विफलता सारांश और एक सुझाया गया समाधान देता है। यह गाइड उस पृष्ठ को पढ़ने, Orbit द्वारा नाम से पहचानी जाने वाली विफलताओं, ऐसी विफलताओं जिन्हें वह नहीं पहचानता, और यह समझाता है कि जब बिल्ड सफल हो जाता है लेकिन साइट अभी भी गलत है तो क्या करें।

विफलता को पढ़ना

Kapsule Orbit में अपनी परियोजना खोलें।
डिप्लॉयमेंट टैब खोलें।
विफल स्थिति वाली डिप्लॉयमेंट पर क्लिक करें।
लॉग से पहले विफलता सारांश पढ़ें, फिर लॉग को स्वयं पढ़ें।

विफल डिप्लॉयमेंट वर्गीकृत विफलता सारांश दिखा रहा है

Kapsule Orbit प्रत्येक विफलता को एक श्रेणी प्रदान करता है: मेमोरी से बाहर, संकलन त्रुटि, परीक्षण विफलता, लिंट त्रुटि, इंस्टॉल त्रुटि, नेटवर्क त्रुटि, टाइमआउट, या अज्ञात त्रुटि। श्रेणी आपको बताती है कि एक भी लॉग लाइन पढ़ने से पहले पाइपलाइन के किस हिस्से को देखना चाहिए।

एक AI निदान प्राप्त करें बटन भी है। यह लॉग की अंतिम 120 पंक्तियों को पता चली गई फ्रेमवर्क और विफलता श्रेणी के साथ पढ़ता है और एक सादी भाषा में स्पष्टीकरण देता है।

निदान AI-उत्पन्न, कार्य करने से पहले सत्यापित करें लेबल किया गया है। इसे लॉग की सही पंक्ति के लिए एक बहुत अच्छे संकेत के रूप में मानें, न कि आपके कोडबेस पर अधिकार के रूप में। कुछ भी बदलने से पहले जिस पंक्ति का यह संदर्भ देता है उसे पढ़ें।

यदि बिल्ड कभी शुरू नहीं हुई और कतार में अटकी है, तो नीचे कतारबद्ध बिल्ड अनुभाग पर जाएं।

विफलताएं जिन्हें Kapsule Orbit नाम से पहचानता है

ये डिप्लॉयमेंट पृष्ठ पर एक विशिष्ट सुझाया गया समाधान के साथ आते हैं।

क्या Kapsule Orbit पहचानता है	इसका क्या मतलब है	समाधान
लापता मॉड्यूल	एक आयात एक पैकेज की ओर इशारा करता है जो स्थापित नहीं है	पैकेज को `package.json` में जोड़ें और कमिट करें, या आयात पाथ में टाइपो को ठीक करें
`ERESOLVE` संघर्ष	npm एक सहकर्मी निर्भरता को संतुष्ट नहीं कर सकता	`package.json` में संघर्ष को हल करें, या अपनी इंस्टॉल कमांड में `--legacy-peer-deps` जोड़ें सेटिंग्स में
TypeScript त्रुटि	बिल्ड के दौरान टाइप जांच विफल हुई	सूचीबद्ध त्रुटियों को ठीक करें। तृतीय-पक्ष टाइप समस्याओं के लिए, `tsconfig.json` में `skipLibCheck: true`
मेमोरी से बाहर	बिल्ड ने बिल्ड मशीन की RAM को अतिक्रम किया	`NODE_OPTIONS=--max-old-space-size=2048` को एक पर्यावरण चर के रूप में जोड़ें, या बड़ी बिल्ड मशीन वाली योजना में जाएं
बिल्ड डिस्क भरी हुई है	बिल्ड ने अपनी डिस्क को भर दिया	असामान्य रूप से बड़े `node_modules` या आर्टिफ़ैक्ट को देखें, या बड़ी बिल्ड डिस्क वाली योजना में जाएं
बिल्ड टाइमआउट हुआ	बिल्ड ने 30 मिनट की सीमा को हिट किया	बिल्ड कैश सक्षम करें, बंडल आकार को कम करें, या यह पता करें कि क्या लटका हुआ है
पैकेज नहीं मिला (404)	एक निर्भरता उस नाम या संस्करण पर मौजूद नहीं है	`package.json` में टाइपो के लिए जांचें, या पुष्टि करें कि पैकेज प्रकाशित है
ESLint त्रुटियां	लिंट त्रुटियों ने बिल्ड को अवरुद्ध किया	उन्हें ठीक करें, या अपनी फ्रेमवर्क कॉन्फ़िग में लिंट विफल होना बंद करें
सिंटैक्स त्रुटि	पार्स न किया जाने योग्य स्रोत	लापता कोष्ठक, बंद न किया गया स्ट्रिंग, या सिंटैक्स जिसे आपका Node संस्करण समर्थन नहीं करता
फ़ाइल नहीं मिली	एक संदर्भित फ़ाइल रिपोजिटरी में नहीं है	पुष्टि करें कि यह कमिट किया गया है, और पाथ की केस जांचें
लॉकफ़ाइल पुरानी है	लॉकफ़ाइल `package.json` से मेल नहीं खाती	अपने पैकेज मैनेजर को स्थानीय रूप से इंस्टॉल करें और अपडेट की गई लॉकफ़ाइल को कमिट करें

लॉकफ़ाइल असमानता एकल सबसे आम पहली-डिप्लॉय विफलता है, और सबसे भ्रामक है, क्योंकि यह स्थानीय रूप से कभी नहीं होता। npm ci, yarn install --frozen-lockfile और pnpm install --frozen-lockfile सभी जारी रखने से इनकार करते हैं जब लॉकफ़ाइल package.json से असहमत हो। लॉकफ़ाइल को स्थानीय रूप से पुनर्जन्म दें और इसे कमिट करें।

चरण द्वारा सामान्य विफलताएं

निर्भरता इंस्टॉल विफल

इंस्टॉल चरण में त्रुटि हुई।

गलत पैकेज मैनेजर। Kapsule Orbit आपकी लॉकफ़ाइल से npm, yarn या pnpm चुनता है। यदि एक से अधिक लॉकफ़ाइलें कमिट की गई हैं, तो पसंद वह नहीं हो सकता जो आप उम्मीद करते हैं। उन लोगों को हटाएं जिनका आप उपयोग नहीं कर रहे हैं, या सेटिंग्स में इंस्टॉल कमांड को स्पष्ट रूप से सेट करें।
निजी रजिस्ट्री। यदि एक निर्भरता एक निजी रजिस्ट्री से आती है, तो auth टोकन को बिल्ड समय पर एक पर्यावरण चर के रूप में उपलब्ध होना चाहिए, और आपके .npmrc को इसका संदर्भ देना चाहिए।
Node.js संस्करण असमानता। कुछ पैकेजों के लिए न्यूनतम Node संस्करण की आवश्यकता होती है। सेटिंग्स में Node.js संस्करण को मुख्य संस्करण संख्या पर सेट करें: 18, 20 या 22।
बड़े मोनोरेपो पर मेमोरी से बाहर। npm install के बजाय npm ci का उपयोग करें, और बड़ी बिल्ड मशीन वाली योजना पर विचार करें।

बिल्ड कमांड विफल

बिल्ड चरण में त्रुटि हुई।

TypeScript या लिंट त्रुटियां। Kapsule Orbit आपकी बिल्ड कमांड को बिल्कुल जैसे लिखा गया है उसे चलाता है। यदि आपकी बिल्ड स्थानीय रूप से विफल होती है, तो यह यहां विफल हो जाती है।
लापता बिल्ड-समय पर्यावरण चर। एक चर जो बिल्ड के दौरान पढ़ा जाता है, उसे बिल्ड चलने से पहले मौजूद होना चाहिए, न कि रनटाइम पर। इसे Env vars टैब पर जोड़ें और फिर से डिप्लॉय करें। डिप्लॉयमेंट के बाद जोड़ा गया बिल्ड-समय चर पूर्वव्यापी रूप से इसे लागू नहीं करता है।
मोनोरेपो में गलत रूट निर्देशिका। सेटिंग्स में रूट निर्देशिका को ऐप के पाथ पर सेट करें, उदाहरण के लिए apps/web।

बिल्ड टाइमआउट करता है

बिल्ड हर योजना पर वॉल-क्लॉक समय के 30 मिनट पर बंद कर दी जाती हैं। यदि आपका लगातार उस दृष्टिकोण के करीब है:

लॉग में एक प्रक्रिया के लिए इनपुट का इंतजार कर रहे हैं। एक बिल्ड जो संकेत देती है वह एक बिल्ड है जो लटकी हुई है।
--legacy-peer-deps से बचें बड़े निर्भरता पेड़ पर जब तक आपको इसकी आवश्यकता न हो।
सुनिश्चित करें कि बिल्ड कैश का उपयोग किया जा रहा है। Liftoff और Apex योजनाओं में इसे शामिल है; डिप्लॉयमेंट पृष्ठ कैश हिट या कोल्ड बिल्ड दिखाता है।
अधिक बिल्ड vCPU वाली योजना में जाएं। Kapsule Orbit योजना सीमा देखें।

बिल्ड कभी शुरू नहीं होता

कतार में अटकी डिप्लॉयमेंट एक बिल्ड स्लॉट की प्रतीक्षा कर रही है। विवरण पृष्ठ आपकी कतार स्थिति दिखाता है और आपके कितने समवर्ती बिल्ड स्लॉट उपयोग में हैं, और जब कोई खाली हो जाता है तो स्वचालित रूप से बिल्ड शुरू करता है। Launch और Liftoff एक समवर्ती बिल्ड की अनुमति देते हैं; Apex तीन की अनुमति देता है।

आप अपने खाते में Kapsule Orbit, फिर कतार पर उड़ान में सब कुछ देख सकते हैं।

यदि डिप्लॉयमेंट कतार में बैठा है और कुछ और नहीं चल रहा है, तो यह कतारबद्ध होने की तुलना में अधिक संभव है कि वह रोका जा रहा हो। जांचें:

अनुमोदन की प्रतीक्षा, यदि उत्पादन के लिए अनुमोदन की आवश्यकता है चालू है
परियोजना पर एक डिप्लॉय लॉक
एक डिप्लॉय फ्रीज शेड्यूल वर्तमान समय या दिन को अवरुद्ध कर रहा है
CI आवश्यक जांचें आपकी पाइपलाइन की प्रतीक्षा कर रहे हैं
उत्पादन से पहले स्टेजिंग सफलता की आवश्यकता है एक ही कमिट के स्टेजिंग डिप्लॉय की प्रतीक्षा कर रहा है

बिल्ड पूरी तरह से छोड़ दी गई

यदि एक पुश ने कोई डिप्लॉयमेंट तैयार नहीं की, तो यह संभवतः जानबूझकर फ़िल्टर किया गया था:

अनदेखी पाथ: पुश में हर फ़ाइल *.md या docs/** जैसे पैटर्न से मेल खाती है
शाखा अनदेखी पैटर्न: शाखा dependabot/* जैसे कुछ से मेल खाती है
रूट निर्देशिका: पुश ने इस परियोजना के लिए मोनोरेपो उपनिर्देशिका को नहीं छुआ
शाखा पूर्वावलोकन बंद, और पुश उत्पादन या स्टेजिंग के लिए नहीं था

बिल्ड सफल हुई लेकिन साइट गलत है

एक हरी बिल्ड और एक टूटी साइट लगभग हमेशा एक कोड समस्या के बजाय एक कॉन्फ़िगरेशन समस्या होती है।

हर पृष्ठ पर 404। आउटपुट निर्देशिका गलत है: Kapsule Orbit ने एक फ़ोल्डर प्रकाशित किया जो आपकी बिल्ड आउटपुट नहीं है। जांचें कि आपकी बिल्ड वास्तव में क्या लिखती है। सामान्य मान dist, .next, out, build और .output हैं।

केवल गतिशील मार्गों पर 404। ऐप को एक चलती सर्वर की आवश्यकता है और इसे स्टेटिक फ़ाइलों के रूप में परोसा जा रहा है। सेटिंग्स में रनटाइम के तहत सर्वर मोड चालू करें। यह Next.js के साथ SSR, Remix, Nuxt और कुछ भी के लिए आवश्यक है जो स्टेटिक निर्यात नहीं है।

डिप्लॉय के बाद संपत्ति 404, उन उपयोगकर्ताओं के लिए जो पहले से साइट पर थे। उन्होंने पुरानी पृष्ठ लोड की और पुरानी बंडल URLs का अनुरोध कर रहे हैं जो अब मौजूद नहीं हैं। सेटिंग्स में Skew सुरक्षा चालू करें, जो नई डिप्लॉयमेंट के बाद एक प्रतिधारण विंडो के लिए पिछली बिल्ड की कलाकृतियों को उपलब्ध रखता है।

पर्यावरण चर रनटाइम पर अपरिभाषित है। पुष्टि करें कि चर की गुंजाइश वास्तव में इस पर्यावरण को कवर करती है, और डिप्लॉयमेंट परिवर्तन के बाद आती है। डिप्लॉयमेंट विवरण पृष्ठ सूचीबद्ध करता है कि बिल्ड समय पर कौन सी कुंजियाँ इंजेक्ट की गई थीं और उन्हें आपके वर्तमान कॉन्फ़िगरेशन के विरुद्ध अलग करता है।

फ्रेमवर्क-दर-फ्रेमवर्क बिल्ड सेटिंग्स अपनी बिल्ड कमांड और आउटपुट निर्देशिका को कॉन्फ़िगर करना में हैं।

पुनः प्रयास करना

विफल डिप्लॉयमेंट पृष्ठ पर:

बिल्ड को पुनः प्रयास करें एक ही कमिट को फिर से चलाता है।
अधिक पुनः प्रयास विकल्प, फिर साफ़ किए गए कैश के साथ पुनः प्रयास करें, बिल्ड कैश को पहले हटा देता है।

आप Kapsule Orbit से पुनः प्रयास करने के लिए भी कह सकते हैं। सेटिंग्स में बिल्ड ऑटो-रिट्राई नेटवर्क विफलता या टाइमआउट जैसी अवसंरचना त्रुटियों के कारण विफल बिल्ड को तीन बार तक पुनः कतारबद्ध करता है। यह जानबूझकर कोड त्रुटियों को पुनः प्रयास नहीं करता है, इसलिए संकलन, लिंट या परीक्षण विफलता कभी भी लूप नहीं करती है।

साफ़ किए गए कैश के साथ पुनः प्रयास करना प्रभाव के लिए पर्यावरण के node_modules को हटा देता है और यह पूर्ववत नहीं किया जा सकता है। इसके बाद की अगली बिल्ड धीमी होगी। यह बिंदु है, लेकिन बड़े मोनोरेपो पर इसे आत्मनिर्भर रूप से न करें।

एक बुरी बिल्ड को उपयोगकर्ताओं तक पहुंचने से रोकना

यदि डिप्लॉयमेंट पहले से ही चल रहा है और कुछ टूट गया है, तो दबाव के तहत आगे बढ़ने का प्रयास करने के बजाय रोलबैक करें। रोलबैक पहले से बनी हुई कलाकृति को बढ़ावा देता है और कुछ सेकंड लगते हैं। डिप्लॉयमेंट को रोलबैक करना देखें।

जब तक आप जांच करते हैं, तब तक आगे की डिप्लॉयमेंट को रोकने के लिए, परियोजना पर डिप्लॉय को लॉक करें पर क्लिक करें। पुश-ट्रिगर्ड डिप्लॉयमेंट तब तक छोड़ दी जाती हैं जब तक आप अनलॉक न करें, जबकि मैनुअल डिप्लॉयमेंट अभी भी काम करती हैं ताकि आप समाधान को जहाज कर सकें।

आप Kapsule Orbit को यह स्वचालित रूप से भी कर सकते हैं: विफलता पर ऑटो-रोलबैक जब एक उत्पादन डिप्लॉयमेंट विफल होती है तो अंतिम स्वस्थ डिप्लॉयमेंट को पुनर्स्थापित करता है, और एक स्वास्थ्य जांच पाथ इसे पुनर्स्थापित करता है जब नई डिप्लॉयमेंट 15 सेकंड के भीतर 2xx के साथ उत्तर नहीं देती है।

अभी भी अटका हुआ

यदि लॉग बस कोई त्रुटि संदेश के साथ समाप्त हो जाता है, तो बिल्ड प्रक्रिया सबसे अधिक संभावना से मार दी गई थी: मेमोरी से बाहर, या बिल्ड मशीन को वापस ले लिया गया था। एक बार पुनः प्रयास करें। यदि यह एक ही तरीके से दो बार विफल हो जाता है, तो KPanel से एक टिकट खोलें या support@kapsulehost.com को ईमेल करें और विवरण पृष्ठ पर दिखाई गई डिप्लॉयमेंट ID को शामिल करें।