Troubleshootingפתרון תקלות
Ordered by how often they happen, not by how interesting they are. Every entry ends with a command you can paste.
מסודר לפי תדירות, לא לפי כמה מעניין. כל סעיף מסתיים בפקודה שאפשר להדביק.
Build failuresכשלי בנייה
Build works locally, fails on Shipyardהבנייה עובדת מקומית ונכשלת ב-Shipyard
Almost always one of three things: a dependency you have installed globally and never declared, a file excluded by .shipyardignore or .gitignore that the build needs, or a Node version mismatch. Check the version first, it is the cheapest.
כמעט תמיד אחד משלושה: תלות שמותקנת אצלכם גלובלית ומעולם לא הוצהרה, קובץ שהוחרג ב-.shipyardignore או .gitignore שהבנייה צריכה, או אי-התאמת גרסת Node. בדקו את הגרסה קודם, זה הזול ביותר.
$ shipyard logs --deployment dep_7Kq2 --phase build $ node -v # compare with runtime.node in shipyard.yaml
Out of memory during buildחריגת זיכרון בזמן בנייה
Large Next.js and monorepo builds hit the default heap. Raise it in shipyard.yaml rather than in a script, so it applies to every builder invocation.
בניות גדולות של Next.js ומונו-ריפו מגיעות לגבול הערימה. הגדילו ב-shipyard.yaml ולא בסקריפט, כדי שזה יחול על כל הפעלת בנאי.
build:
env:
NODE_OPTIONS: --max-old-space-size=4096Wrong builder detectedזוהה בנאי שגוי
Detection reads your package.json and framework config. In a monorepo it can guess wrong. Say it explicitly.
הזיהוי קורא את package.json ואת קונפיג הפריימוורק. במונו-ריפו הוא עלול לטעות. הצהירו במפורש.
build: builder: nextjs-standalone root: apps/web
Deploy blocked by the scannerהפריסה נחסמה על ידי הסורק
Exit code 4, status blocked, previous release still serving. This is the system working. Read the report, fix the finding, deploy again.
קוד יציאה 4, סטטוס blocked, השחרור הקודם עדיין משרת. זו המערכת עובדת. קראו את הדוח, תקנו את הממצא, פרסו שוב.
$ shipyard security report --deployment dep_7Kq2
secret-in-imageA .env file got baked into a layer. Add it to .shipyardignore and set the values with shipyard env set.קובץ .env נצרב לשכבה. הוסיפו אותו ל-.shipyardignore והגדירו את הערכים עם shipyard env set.cve-*Update the named dependency to the named version. The report gives you both.עדכנו את התלות הנקובה לגרסה הנקובה. הדוח נותן לכם את שתיהן.runs-as-rootOnly reachable with a custom Dockerfile. Add a USER line.מגיעים לזה רק עם Dockerfile מותאם. הוסיפו שורת USER.source-maps-publicDisable production source maps, or accept the finding as informational if you publish them deliberately.כבו מפות מקור בייצור, או קבלו את הממצא כמידע אם אתם מפרסמים אותן במכוון.The app deploys but does not respondהאפליקציה נפרסת אבל לא מגיבה
This is the single most common cause. A process listening on 127.0.0.1 inside a container is unreachable from outside it. Listen on 0.0.0.0 and on process.env.PORT, which we set. Do not hardcode 3000.
זו הסיבה הנפוצה ביותר. תהליך שמאזין ל-127.0.0.1 בתוך קונטיינר אינו נגיש מבחוץ. האזינו ל-0.0.0.0 ול-process.env.PORT, שאנחנו מגדירים. אל תקבעו 3000 קשיח.
const port = Number(process.env.PORT) || 3000; app.listen(port, '0.0.0.0');
Other causes, in order: the health check path returns a non-200, the process exits immediately on a missing environment variable, or startup takes longer than the health check grace period.
סיבות אחרות, לפי סדר: נתיב בדיקת התקינות מחזיר לא-200, התהליך יוצא מיד בגלל משתנה סביבה חסר, או שההפעלה אורכת יותר מחלון החסד של בדיקת התקינות.
$ shipyard logs --tail 100 $ shipyard ps
Environment variablesמשתני סביבה
Variable is set but undefined in the appהמשתנה מוגדר אבל undefined באפליקציה
- You set it on the wrong environment.
shipyard env list --env productionand check.הגדרתם אותו בסביבה הלא נכונה. הריצוshipyard env list --env productionובדקו. - You set it after the deploy. Values are injected at container start, so a new deploy or restart is required.הגדרתם אותו אחרי הפריסה. הערכים מוזרקים בהפעלת הקונטיינר, ולכן נדרשת פריסה או הפעלה מחדש.
- You expected it at build time. Runtime variables are not available to the builder; use
build.envfor that, and never put a secret there.ציפיתם לו בזמן בנייה. משתני ריצה אינם זמינים לבנאי; השתמשו ב-build.envלזה, ולעולם אל תשימו שם סוד.
Domains and TLSדומיינים ו-TLS
pending_dnsYour CNAME or A record has not propagated yet, or points elsewhere. Verify with dig, then wait.רשומת ה-CNAME או ה-A שלכם עדיין לא התפשטה, או מצביעה למקום אחר. אמתו עם dig, ואז חכו.pending_tlsDNS is correct and the certificate is being issued. Normally under two minutes.ה-DNS תקין והתעודה מונפקת. בדרך כלל פחות משתי דקות.failedIssuance was refused. Almost always a CAA record that excludes our issuer, or a proxy in front of us intercepting the challenge.ההנפקה סורבה. כמעט תמיד רשומת CAA שמחריגה את המנפיק שלנו, או פרוקסי לפנינו שחוטף את האתגר.$ shipyard domains list $ dig +short app.example.com $ dig +short CAA example.com
CLI and authenticationCLI ואימות
exit 2Not authenticated. Run shipyard login, or export SHIPYARD_API_KEY.לא מאומת. הריצו shipyard login, או ייצאו SHIPYARD_API_KEY.exit 3Authenticated but not authorised. Your key lacks the scope, most often deploy:prod.מאומת אך לא מורשה. למפתח חסרה ההרשאה, לרוב deploy:prod.exit 5Rate limited. Back off; the CLI already retries.הוגבל בקצב. המתינו; ה-CLI כבר מנסה שוב.exit 6No shipyard.yaml found. You are in the wrong directory, or you never ran shipyard init.לא נמצא shipyard.yaml. אתם בתיקייה הלא נכונה, או שמעולם לא הרצתם shipyard init.Agent and MCP problemsבעיות סוכן ו-MCP
- “No credentials” from the MCP server means neither
SHIPYARD_API_KEYnor~/.shipyard/credentialswas found in the process the agent spawned. Pass the key with-ewhen you add the server.”No credentials“ משרת ה-MCP אומר שלא נמצאו לאSHIPYARD_API_KEYולא~/.shipyard/credentialsבתהליך שהסוכן הפעיל. העבירו את המפתח עם-eכשאתם מוסיפים את השרת. - The agent says it cannot deploy to production. That is correct if its key is scoped to
deploy:staging. Keep it that way and promote yourself.הסוכן אומר שהוא לא יכול לפרוס לייצור. זה נכון אם המפתח שלו מוגבל ל-deploy:staging. השאירו את זה כך וקדמו בעצמכם. - The agent cannot read a secret. Also correct. There is no read path for values, for anyone.הסוכן לא יכול לקרוא סוד. גם זה נכון. אין מסלול קריאה לערכים, לאף אחד.
When none of this helpsכשכלום מזה לא עוזר
Send us the deployment id (dep_…) or a request_id from an API error. With either one we can find the exact request without a back-and-forth. shipyard@interhost.net, or support@interhost.net if you already have an Interhost account.
שלחו לנו את מזהה הפריסה (dep_…) או request_id משגיאת API. עם אחד מהם נוכל למצוא את הבקשה המדויקת בלי הלוך ושוב. shipyard@interhost.net, או support@interhost.net אם כבר יש לכם חשבון באינטרהוסט.