ساخت شکست خورد

گزارش ساخت را باز کنید و از آخر بخوانید. خط‌های قرمز آخر معمولاً علت اصلی‌اند و بقیه نتیجهٔ همان‌اند. در زیر، هر بخش با متنی شروع می‌شود که در گزارش می‌بینید.

Cannot find module 'X' (Node.js)

وابستگی در package.json نیست، یا در devDependencies است و در محیط production نصب نمی‌شود، یا lock file با package.json هماهنگ نیست.

• بسته را به dependencies اضافه کنید: npm install X
• package-lock.json (یا pnpm-lock.yaml، yarn.lock) را commit کنید.
• اگر مسیر محلی است (Cannot find module '@/components/Header')، حروف کوچک و بزرگ نام فایل را بررسی کنید. لینوکس به آن‌ها حساس است؛ header.tsx با Header.tsx فرق دارد.

ModuleNotFoundError: No module named 'X' (Python)

بسته در requirements.txt یا pyproject.toml نیست. اضافه‌اش کنید. نام بسته گاهی با نام import فرق دارد (import cv2 از بستهٔ opencv-python-headless می‌آید، import yaml از PyYAML).

JavaScript heap out of memory، Killed، exit code 137

ساخت حافظه کم آورد. برای Node.js، متغیر زمان ساخت NODE_OPTIONS=--max-old-space-size=2048 را اضافه کنید. اگر پروژه خیلی بزرگ است (مثلاً Next.js با هزاران صفحه)، پلن با سقف RAM بیشتر لازم است.

متغیری در زمان ساخت پیدا نمی‌شود

متغیرهایی مثل NEXT_PUBLIC_* یا VITE_* باید بیلد تایم باشند. اگر ران‌تایم تعریفشان کرده‌اید، ساخت آن‌ها را نمی‌بیند. زمان ساخت یا زمان اجرا

نسخهٔ زبان

خط اول گزارش می‌گوید کدام نسخه انتخاب شده و از کجا (Using Node.js 22 (from .nvmrc: "22")). اگر نسخهٔ پروژه در گردو نباشد، گزارش می‌گوید و نزدیک‌ترین نسخه را برمی‌دارد. اگر کد با آن نسخه کار نمی‌کند، نسخه را با NODE_VERSION (یا PYTHON_VERSION و بقیه) روی یکی از نسخه‌های موجود بگذارید. نسخه‌های موجود

استک اشتباه تشخیص داده شده

مثلاً پروژهٔ React شما به شکل Node.js ساخته شده یا برعکس. در تنظیمات سرویس «استک» را دستی انتخاب کنید. تشخیص استک

No Node entrypoint found یا No Python entrypoint found

گردو نمی‌داند برنامه را چطور اجرا کند. در package.json اسکریپت start بگذارید، یا فایل app.py/main.py داشته باشید، یا در تنظیمات سرویس «دستور اجرا» را بنویسید.

پروژه در زیرپوشه است

اگر کد در backend/ یا apps/web است و گزارش می‌گوید package.json پیدا نشد، «پوشهٔ ریشه» را تنظیم کنید. monorepo

خطا در Dockerfile

• COPY failed: file not found: مسیرها نسبت به «زمینهٔ ساخت» حساب می‌شوند. اگر Dockerfile در زیرپوشه است، زمینهٔ ساخت را درست بگذارید.
• ایمیج پایه پیدا نشد: نام و تگ FROM را بررسی کنید.

could not read Username

گردو نتوانست مخزن خصوصی را clone کند. یک بار دیگر ساخت را اجرا کنید. اگر تکرار شد، اتصال GitHub را بررسی کنید.

خطاهای موقت از سمت گردو

اگر بنر خطا می‌گوید مشکل از سمت ساخت گردو است («not in the app»)، مثلاً:

• ایمیج پایه از رجیستری دریافت نشد (i/o timeout، TLS handshake timeout)؛
• بسته‌ها از آینهٔ داخلی دانلود نشدند (503، ETIMEDOUT، socket hang up)؛

در کد چیزی را عوض نکنید. چند دقیقه بعد دوباره استقرار کنید؛ تیم گردو خودکار خبردار می‌شود. اگر بیشتر از نیم ساعت ادامه داشت، تیکت بزنید.