Crescendo Lab ドキュメント
日本語
無料で始める

デプロイのトラブルシューティング

バージョンが失敗したら、まずバージョンのページで理由を確認します。内容が受け付けられなかった場合は修正して再アップロードし、プラットフォームのエラーなら再試行します。

最終更新

内容が受け付けられなかった#

表示される内容原因対処
このソースのビルド方法がわからないzip の最上位に package.json、index.html、Dockerfile がない。プロジェクトフォルダの中から zip にするか、ソースコードからデプロイを参照。
プロジェクトはサービスなのに、アップロードが通常のファイルとして読まれたzip の最上位に Dockerfile もマニフェスト(package.json、go.mod、pyproject.toml、requirements.txt、setup.py)もない。プロジェクトが backend/ などのサブフォルダにある。「設定 › ビルド設定」でルートディレクトリをそのフォルダにして、もう一度デプロイ。失敗の表示に候補のフォルダが出ます。
index.html が見つからないフォルダの中身ではなく、フォルダごと圧縮しています。フォルダの中で圧縮し、index.html を最上位に置きます。
ファイル内にシークレットがあるAPI キーやトークンらしき文字列が含まれています。ファイルから削除し、キーを交換したうえでプロジェクトの「設定」に入力して、再アップロードします。
イメージに CMD がないDockerfile に起動コマンドがありません。CMD または ENTRYPOINT を追加します。
USER が存在しないイメージにないユーザーを指定しています。数値の uid か、イメージにあるユーザー(node など)を使います。
重大な脆弱性イメージ内のパッケージに既知の重大な脆弱性があります。検出結果に記載された修正版にパッケージを上げるか、その版を含む新しいベースイメージに移ります。

ビルドが実行されて失敗した#

失敗コードは buildFailed です。ビルドは始まりましたが、その中のステップが失敗しました。失敗の表示には、失敗したステップ、そのステップが出力した内容、終了時の exit code が含まれます。コンソールではバージョンのページにある失敗表示のログ抜粋を、MCP では sites_deploy_status の failure.buildLog を読みます。

Exit code原因対処
127ビルドが、インストールされていないコマンドを実行しました。たとえばビルドで tsc を実行するのに、package.json の dependencies にも devDependencies にも typescript がない場合です。そのパッケージを追加するか、ビルドコマンドからそのコマンドを外します。

プロジェクトを修正して、もう一度デプロイします。これは新しいアップロードです。同じバージョンを再試行しても、同じように失敗します。

プレビューアドレスが応答しない#

  • Web ページ(静的サイト):バージョンが公開されるまで、プレビューアドレスは 404 site not found を返します。
  • サービス:一度も公開されていないバージョンは起動されないため、公開されるまでプレビューアドレスは 502 service unavailable を返し、ヘッダー X-Sites-Refusal: relay-unavailable が付きます。これはビルドの失敗ではありません。

公開したらすぐに公開アドレスを開いて確認します。正しく動かない場合は、修正してもう一度デプロイします。訪問者より先に問題に気づくには、staging などの別の環境でまずバージョンを試します。

確認待ち#

「先に確認する」に設定されたチェックで問題が見つかると、バージョンは「確認待ち」で止まります。結果を読んだうえで、そのまま公開できます。高い深刻度の脆弱性はこの扱いです。対処は重大な脆弱性と同じで、アップグレードすると警告が消えます。

バージョンが準備完了にならない#

ビルドに成功して公開もされたのに「実行」タブでインスタンスが準備完了にならない場合、多くはサーバーが指定ポートで待ち受けていません。

  1. バージョンのページに imagePortsAmbiguous のお知らせがないか確認します。
  2. サーバーを環境変数 PORT で待ち受けるようにするか、「設定 › 実行設定 › ポート」に実際の待ち受けポートを入力します。
  3. 「サービスを再起動」を選びます。

再起動を繰り返す#

多くは、読み取り専用のファイルシステムで /tmp 以外に書き込もうとしていることが原因です。書き込み先を /tmp に変えてください。コンテナ実行契約をご覧ください。

リクエストが 504 になる、ストリーミングが途中で止まる#

504 に X-AgentLab-Error: platform-timeout が付いている、またはストリーミングのレスポンスが毎回同じ秒数で止まる場合、リクエストがプロジェクトのリクエストの最大時間に達しています。上限を延ばし、リクエストは自動で再送しないでください。リクエストの最大時間をご覧ください。

プラットフォームのエラー#

原因がプラットフォーム側にある場合は、同じバージョンを再試行します。内容の変更も再アップロードも不要です。

1 時間以内にどのビルドマシンにも取り込まれなかったバージョンは、同じ位置で 1 回だけ自動的にキューに戻ります。さらに 1 時間たつと期限切れと表示されます。アップロードから 1 日以内なら同じように再試行できます。それを過ぎたら、もう一度アップロードしてください。

誤ってキューに入れた場合や待ちたくない場合は、キュー待ちの間にキャンセルできます。キュー待ちのビルドをキャンセルするをご覧ください。

それでも解決しない場合#

  • 「実行」タブで、インスタンスの状態と最近のログを確認します。
  • バージョンのページで、プラットフォームが残したお知らせを確認します。
  • Agent Lab MCP に接続した AI ツールに、デプロイの状態を読んでもらいます。このページと同じコードを読み取れます。