Orbit
ビルド失敗のトラブルシューティング
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が名前で認識できるエラー、認識できないエラー、そしてビルドが成功したのにサイトが正常でない場合の対処方法をご説明します。
エラーの読み方
- Orbitでプロジェクトを開きます。
- Deployments(デプロイメント) タブを開きます。
- ステータスが Failed(失敗) のデプロイメントをクリックします。
- ログの上にあるエラー概要を最初に読んでから、ログ自体を読みます。
Orbitはすべてのエラーにカテゴリを割り当てます: Out of memory(メモリ不足)、Compile error(コンパイルエラー)、Test failure(テスト失敗)、Lint error(Lintエラー)、Install error(インストールエラー)、Network error(ネットワークエラー)、Timeout(タイムアウト)、または Unknown error(不明なエラー)。このカテゴリにより、ログ行を1行も読む前に、パイプラインのどの部分を確認すべきかがわかります。
Get AI diagnosis(AI診断を取得) ボタンもあります。ログの最後の120行と検出されたフレームワーク、エラーカテゴリを読み込んで、分かりやすい説明を返します。
診断は AI生成、実行前に検証してください というラベルが付いています。これを、コードベースの権威ではなく、ログの正しい行への非常に優れたポインタとして扱ってください。何かを変更する前に、それが参照する行を読んでください。
ビルドが開始されず Queued(キュー中) のままの場合は、以下の「キュー中のビルド」セクションにスキップしてください。
Orbitが名前で認識するエラー
これらは、デプロイメントページに特定の推奨される修正方法が付属しています。
| Orbitが検出すること | 意味 | 修正 |
|---|---|---|
| Missing module(モジュール不足) | インポートがインストールされていないパッケージを指しています | package.jsonにパッケージを追加してコミットするか、インポートパスのタイプミスを修正します |
ERESOLVE conflict(競合) | npmがピア依存性を満たすことができません | package.jsonの競合を解決するか、設定のインストールコマンドに--legacy-peer-depsを追加します |
| TypeScript error(TypeScriptエラー) | ビルド中のタイプチェックが失敗しました | リストされたエラーを修正してください。サードパーティのタイプの問題については、skipLibCheck: trueをtsconfig.jsonで実行してください |
| Out of memory(メモリ不足) | ビルドがビルドマシンのRAMを超過しました | NODE_OPTIONS=--max-old-space-size=2048を環境変数として追加するか、より大きなビルドマシンを備えたプランに移行してください |
| Build disk full(ビルドディスクが満杯) | ビルドがディスクを満杯にしました | 予期せず大きなnode_modulesまたはアーティファクトを探すか、より大きなビルドディスクを備えたプランに移行してください |
| Build timed out(ビルドがタイムアウト) | ビルドが30分の中止時間に達しました | ビルドキャッシュを有効にするか、バンドルサイズを削減するか、ハングしているものを見つけてください |
| Package not found (404)(パッケージが見つかりません) | 依存性がその名前またはバージョンに存在しません | package.jsonでタイプミスを確認するか、パッケージが公開されていることを確認してください |
| ESLint errors(ESLintエラー) | Lintエラーがビルドをブロックしました | これらを修正するか、フレームワークの設定でLintの失敗を停止してください |
| Syntax error(構文エラー) | 解析不可能なソース | 不足している括弧、閉じられていない文字列、またはNodeバージョンがサポートしていない構文 |
| File not found(ファイルが見つかりません) | 参照されたファイルがリポジトリにありません | コミットされていることを確認し、パスの大文字と小文字を確認してください |
| Lockfile out of date(ロックファイルが古い) | ロックファイルがpackage.jsonと一致しません | パッケージマネージャーのインストールをローカルで実行し、更新されたロックファイルをコミットしてください |
ロックファイルの不一致は、最初のデプロイ失敗で最も一般的で、ローカルでは決して発生しないため、最も混乱を招きます。npm ci、yarn install --frozen-lockfile、pnpm install --frozen-lockfileはすべて、ロックファイルがpackage.jsonと一致しない場合は続行を拒否します。ロックファイルをローカルで再生成してコミットしてください。
フェーズ別の一般的なエラー
依存性のインストールが失敗する
Install(インストール) フェーズでエラーが発生しました。
- 間違ったパッケージマネージャー。 Orbitはロックファイルからnpm、yarn、またはpnpmを選びます。複数のロックファイルがコミットされている場合、選択肢が期待したものではない可能性があります。使用していないものを削除するか、Settings(設定) で Install command(インストールコマンド) を明示的に設定してください。
- プライベートレジストリ。 依存性がプライベートレジストリから来ている場合、認証トークンをビルド時に環境変数として利用可能にする必要があり、
.npmrcがそれを参照する必要があります。 - Node.jsバージョンの不一致。 一部のパッケージには最小Node.jsバージョンが必要です。Settings(設定) で Node.js version(Node.jsバージョン) をメジャーバージョン番号に設定してください:
18、20、または22。 - 大規模なモノレポでのメモリ不足。
npm installではなくnpm ciを使用し、より大きなビルドマシンを備えたプランの検討してください。
ビルドコマンドが失敗する
Build(ビルド) フェーズでエラーが発生しました。
- TypeScriptまたはLintエラー。 Orbitは記述されたとおりにビルドコマンドを実行します。ビルドがローカルで失敗した場合、ここでも失敗します。
- ビルド時の環境変数の不足。 ビルド中に読み取られる変数は、実行時ではなく、ビルドが実行される前に存在する必要があります。Env vars(環境変数) タブに追加して再デプロイしてください。デプロイメント後に追加されたビルド時変数は、それに遡及的に適用されません。
- モノレポ内の間違ったルートディレクトリ。 Settings(設定) で Root directory(ルートディレクトリ) をアプリのパス(例:
apps/web)に設定してください。
ビルドがタイムアウトする
ビルドは、すべてのプランで30分の実時間に達すると中止されます。ビルドが一貫してその時間に近づいている場合:
- ログで入力を待機しているプロセスを確認してください。プロンプトが表示されるビルドはハングするビルドです。
- 大規模な依存性ツリーで必要でない限り
--legacy-peer-depsを避けてください。 - ビルドキャッシュが使用されていることを確認してください。LiftoffプランとApexプランに含まれており、デプロイメントページには Cache hit(キャッシュヒット) または Cold build(コールドビルド) が表示されます。
- より多くのビルドvCPUを備えたプランに移行してください。Orbit Plan Limits(Orbitプラン制限) を参照してください。
ビルドが開始しない
Queued(キュー中) で立ち往生しているデプロイメントは、ビルドスロットを待機しています。詳細ページにキューの位置と使用中の同時ビルドスロット数が表示され、1つのスロットが解放されると自動的にビルドを開始します。LaunchプランとLiftoffプランでは1つの同時ビルドを許可し、Apexプランでは3つを許可します。
アカウント全体のすべての実行中のデプロイメントは、Orbit から Queue(キュー) で確認できます。
デプロイメントが他に何も実行されていない状態でキューに入ったままの場合、キューに入っているのではなく保持されている可能性が高いです。以下を確認してください:
- Await approval(承認待ち)、Require approval for production(本番環境への承認を要求) がオンの場合
- プロジェクト上の deploy lock(デプロイロック)
- 現在の時間または曜日をブロックしている deploy freeze schedule(デプロイ凍結スケジュール)
- パイプラインで待機している CI required checks(CI必須チェック)
- 同じコミットのステージングデプロイを待機している Require staging success before production(本番環境前のステージング成功が必要)
ビルドが完全にスキップされた
プッシュがデプロイメントを生成しなかった場合、それはおそらく意図的にフィルタリングされました:
- Ignored paths(無視されたパス): プッシュ内のすべてのファイルが
*.mdまたはdocs/**のようなパターンに一致しました - Branch ignore patterns(ブランチ無視パターン): ブランチが
dependabot/*のようなものに一致しました - Root directory(ルートディレクトリ): プッシュがこのプロジェクトのモノレポサブディレクトリに何も触れなかった
- Branch previews(ブランチプレビュー) がオフで、プッシュが本番環境またはステージング環境ではなかった
ビルドが成功したがサイトが正常でない
緑色のビルドと壊れたサイトは、ほぼ常に、コードの問題ではなく設定の問題です。
すべてのページで404。 Output directory(出力ディレクトリ) が間違っています: Orbitはビルド出力ではないフォルダを公開しました。ビルドが実際に何を書き込むか確認してください。一般的な値はdist、.next、out、build、.outputです。
動的ルートでのみ404。 アプリは実行中のサーバーが必要であり、静的ファイルとして提供されています。Settings(設定) の Runtime(ランタイム) で Server mode(サーバーモード) をオンにしてください。これは、SSRを使用したNext.js、Remix、Nuxt、および静的エクスポート以外のものすべてに必要です。
デプロイ後にアセットが404になり、既にサイトにいたユーザーが対象です。 古いページを読み込んで、もう存在しない古いバンドルURLをリクエストしています。Settings(設定) で Skew protection(スキュー保護) をオンにします。これにより、新しいデプロイメントがライブになった後の保持期間中、以前のビルドのアーティファクトが利用可能に保たれます。
環境変数がランタイムで未定義。 変数のスコープが実際にこの環境をカバーしていることを確認し、デプロイメントが変更より後の日付であることを確認してください。デプロイメント詳細ページには、ビルド時に注入された正確なキーと現在の設定との差分が一覧表示されます。
フレームワークごとのビルド設定は Configuring Your Build Command and Output Directory(ビルドコマンドと出力ディレクトリの設定) にあります。
再試行
失敗したデプロイメントページで:
- Retry build(ビルドを再試行) は同じコミットを再実行します。
- More retry options(その他の再試行オプション)、次に Retry with cleared cache(キャッシュをクリアして再試行) は、最初にビルドキャッシュを削除します。
Orbitに自動的に再試行させることもできます。Settings(設定) の Build auto-retry(ビルドの自動再試行) は、ネットワークエラーやタイムアウトなどのインフラストラクチャエラーが原因の失敗したビルドを最大3回まで再キューイングします。コードエラーの再試行は意図的に行わないため、コンパイル、Lint、またはテスト失敗は決してループしません。
キャッシュをクリアして再試行すると、環境のnode_modulesキャッシュが削除され、元に戻すことができません。その後の次のビルドは遅くなります。これが要点ですが、大規模なモノレポで無意識のうちに実行しないでください。
不正なビルドがユーザーに到達するのを防ぐ
デプロイが既にライブになり、何かを破損している場合は、プレッシャーの下で前方への修正を試みるのではなく、ロールバックしてください。ロールバックは既にビルドされたアーティファクトを昇格させ、数秒で完了します。Rolling Back a Deployment(デプロイメントのロールバック) を参照してください。
調査中のさらなるデプロイを停止するには、プロジェクト上の Lock deploys(デプロイをロック) をクリックしてください。プッシュトリガーされたデプロイメントは、ロック解除されるまでスキップされますが、修正を発送できるように手動デプロイメントは引き続き機能します。
Orbitにこれを自動的に実行させることもできます: Auto-rollback on failure(失敗時の自動ロールバック) は本番環境デプロイメントが失敗した場合、最後の正常なデプロイメントを復元し、Health check(ヘルスチェック) パスは新しいデプロイメントが15秒以内に2xxで応答しない場合に復元します。
まだ行き詰まっている
ログがエラーメッセージなしで単に終了した場合、ビルドプロセスはおそらく強制終了されました: メモリ不足、またはビルドマシンが回収されました。1回再試行してください。2回同じ方法で失敗した場合は、KPanelからチケットを開くか、support@kapsulehost.com にメールを送信して、詳細ページに表示されるデプロイメントIDを含めてください。