トラブルシューティング

デプロイに失敗したときや、アプリが期待どおりに動かないときの確認方法をまとめています。AI エージェントには、起きたこととエラーメッセージを伝えて、原因の調査を依頼できます。

症状から探す

症状	確認する項目
デプロイできない	どこで止まったかを特定する
アプリを開けない	アクセス権限、利用枠、応答の時間制限
更新が見えない	画面の更新、シークレットの反映
データが残らない	データの保存先
定期実行やバックグラウンド処理が動かない	定期実行の確認、処理方法の確認

AI エージェントに調査を頼む

このアプリで［操作］をすると［症状］が起きます。発生したのは［日時］です。状態とログを確認し、原因と対応方法を教えてください。

エラーコード（code）、メッセージ（message）、対処のヒント（hint）が表示されていれば、一緒に伝えます。サービス側の障害など、アプリの修正では解決しない場合は、サポートに問い合わせるの情報をまとめます。

どこで止まったかを特定する

コンソールでは、アプリ画面の「概要」に失敗の要約、「デプロイ」の「ログを表示」にデプロイログ、「ログ」にアプリログがあります。まず概要を確認し、必要に応じてエージェントに詳細を調べてもらいます。

CLI とログの詳細

deploy_id はデプロイを識別する ID で、CLI の出力やコンソールの「デプロイ」タブで確認できます。

keelson status                   # アプリと直近デプロイの状態
keelson diagnose <deploy_id>     # 失敗したデプロイの診断
keelson logs deploy <deploy_id>  # 進行ログと失敗したデプロイの詳細
keelson logs app <slug>          # アプリの標準出力・標準エラー

起動中にアプリが終了した場合も、keelson logs deploy や keelson diagnose から保存済みの起動ログを確認できます。エラーが起きたコードの位置や、必要な設定が足りないことなどが記録されます。

保存されるログの範囲

失敗したデプロイでは、ビルドや起動の詳細が保存されます。依存パッケージや Dockerfile、シークレット、設定、マイグレーションのエラーを後から調べるときにも使えます。起動時の例外の記録（traceback）やプロセスエラーは、保存済みの起動ログを確認します。

成功したデプロイのビルド出力は保存されません。進行ログも保存済みの失敗詳細もない場合は、ログがない理由が表示されます。

止まった場所	見るもの	よくある原因
アップロード前（CLI の事前チェック）	コマンドの出力	Go アプリに `go.mod` がない、Node アプリに pnpm / yarn 用ロックファイルしかない、`command` に `pip install`、`db.mode` がない、`env` の値が引用符なし
検証	`code` と `message`	`workers` / `databases` が残っている、予約名、プラン上限
ビルド	デプロイログ	依存の解決失敗、`package.json` と `package-lock.json` の不一致、非公開のパッケージ配布先（private registry）、cgo が必要な Go パッケージ、ビルドスクリプトのエラー
起動	`keelson logs deploy <deploy_id>` の保存済みのアプリの起動ログ	`0.0.0.0` で listen していない、`PORT` のハードコード、未設定のシークレットで例外
ヘルスチェック	保存済みのアプリの起動ログ、その後にアプリログ	アプリが起動中に終了、`/` が 5xx、起動に 120 秒以上かかる
マイグレーション	デプロイログ	`db.migrate` の SQL エラー。以前のバージョンへのアクセスは維持されますが、マイグレーションが加えた DB の変更は自動では戻りません。DB の状態を確認してから直します
動いているが期待どおりでない	アプリログ、アクセスログ	下の「よくある失敗」

よくある失敗

デプロイ中に Ctrl-C を押した

Ctrl-C で止まるのは、このクライアントによる監視だけです。デプロイはサーバー側で続いています。そのまま新しいバージョンへ切り替わることがあるため、CLI に表示された deploy_id で進行状況を確認します。

keelson status <deploy_id>

新しいバージョンを使わない場合は、デプロイの完了後に以前のコードへ戻します。コンテナイメージが残っている過去の成功したデプロイには、次のコマンドで戻せます。DB の変更は戻りません。

keelson rollback --app <slug>

静的サイト / SPA はロールバックの対象外です。以前のファイルを再デプロイします。手順は更新と復元を参照してください。

戻せるデプロイがない場合など、いったん利用を止めたいときは、デプロイ完了後にサスペンドします。

keelson app stop --app <slug>

ローカルでは動くが Keelson で落ちる

手元と Keelson で設定や保存先が異なる可能性があります。エージェントには、次の点を確認してもらいます。

手元からの接続だけを受け付けている — 待ち受けアドレスを localhost から 0.0.0.0 に変える
接続を受け付けるポート番号をコードで固定している — PORT 環境変数から読む
ローカルにしかないファイルに依存している — .env、ローカルの DB ファイル、.gitignore 済みのファイル。keelson deploy --check --json の archive.excluded で、何が除外されたか分かります
環境変数が未設定 — ローカルの .env にだけある値は Keelson にはありません。secrets に宣言して値を設定する
ローカルの SQLite ファイルを使っている — /data も /tmp も再起動後にデータが残りません。Managed SQLite への移行を検討する

Node アプリのロックファイルが拒否される

Keelson の Node ビルダーは npm を使うため、依存を固定するには npm 用の package-lock.json が必要です。エージェントに、プロジェクトのルートで npm install を実行して package-lock.json を生成し、依存関係の整合性を確認してから再デプロイするよう依頼します。生成したファイルはソースコードと一緒に管理します。

pnpm-lock.yaml や yarn.lock は削除しなくてかまいません。package-lock.json と同居していてもデプロイでき、ビルドには package-lock.json が使われます。

データが消える

保存先がアプリのサーバー内のファイルになっていないか確認します。/tmp、/data、アプリディレクトリのファイルは、再起動・再デプロイ・アイドル停止で失われます。データベースか Files / Media SDK に置きます。

バックグラウンド処理が動かない

サーバー側でレスポンスを返した後に続ける処理は、最後まで実行されることが保証されません。また、アプリ内のタイマーは、アプリの停止中には動きません。

エージェントに、そのリクエストで必要な処理は応答を返すまでに完了させ、定期的な処理は Keelson の定期実行ジョブへ移すよう依頼します。後でまとめて処理する場合は、未処理の内容を DB に保存する方法もありますが、次の実行まで待ち時間が生じます。ブラウザ側のタイマーは、この制約の対象外です。詳しくはアプリが動くタイミングを参照してください。

定期実行（cron）が動かない

スケジュールがプランの最小間隔より短くないか（デプロイ時に拒否されます）
前回の実行が終わっていないか（重複実行はスキップされます）
月間実行回数の上限に達していないか（当月はスキップ）
アプリがサスペンドされていないか
「定期実行」タブの実行履歴で、スキップの理由を確認できます

更新したのに見た目が変わらない

ブラウザに古いファイルが残っている可能性があります。デプロイの完了を確認し、ページを強制再読み込みします（Mac: Cmd + Shift + R / Windows: Ctrl + Shift + R）。

静的サイトの更新は配信先へ順次反映されるため、完了後も少し時間がかかることがあります。変わらない場合は、更新先のアプリとアップロードしたファイルが合っているか、エージェントに確認を依頼します。

利用者が「アクセスできません」と言う

ワークスペースのメンバーか（招待が未承諾でないか）
ブロックされていないか
アプリの閲覧権限があるグループに入っているか
登録されたアカウントでログインしているか
IP 制御で拒否されていないか（403 画面に送信元 IP が出ます）

詳細はメンバーとロール。

「稼働枠が空いていない」（503）

「同時に使えるアプリ数」の上限です。直近 5 分にアクセスがあったアプリと、優先起動を設定したアプリが枠を使っています。予約していない枠を使うアプリへのアクセスが途絶えてから約 5 分待つか、重要なアプリに優先起動を設定するか、プランを上げます。

504 Gateway Timeout

応答までに時間がかかりすぎた場合などに表示されます。Keelson では、応答開始まで 120 秒、ストリーミングを含む全体で 300 秒、ストリーミングの応答間隔で 120 秒の上限があります（HTTP の時間上限）。

エージェントに、時間のかかっている処理を調べ、処理を短くする・結果を少しずつ返す・定期実行に分ける方法を検討してもらいます。ストリーミングでも時間上限はなくなりません。

504 が表示されても、サーバー側では保存や送信が完了している場合があります。再操作する前に結果を確認します。実装では、同じ依頼を繰り返しても重複して保存・送信しない仕組み（冪等性）が必要です。

Webhook が 401 / 403 になる

パスが auth.endpoints に宣言されているか（/api/webhooks/ か /api/external/ で始まる必要があります）
メソッドが宣言と合っているか
トークンのスコープと許可 IP が合っているか

外部システムとの連携。

シークレットを変えたのに反映されない

シークレットは保存しただけでは、動いているアプリに反映されません。コードも更新する場合はデプロイし、値だけを反映する場合はコンソールの「適用」を押します。「適用」は、コードを再アップロード・ビルドせずに再デプロイします（環境変数とシークレット）。

サポートに問い合わせる

deploy.platform.error のようにプラットフォーム側のエラーが出た場合や、上記で解決しない場合は、お問い合わせから連絡してください。

次を添えると、やり取りの往復が減ります。

添えるもの	取り方
ワークスペースの slug	`keelson workspaces list --json` の `slug`（URL は名前の変更前のものが残る場合があります）
アプリの slug	`keelson.yaml` の `slug`、または `keelson apps list --workspace <ワークスペース slug> --json` の `slug`
`deploy_id`	`keelson status --json` の出力、またはコンソールの「デプロイ」タブ
エラーの `code` と `message` と `hint`	CLI の出力をそのまま。`--json` を付けるとまとめて取れます
起きた日時とタイムゾーン	ログを引くときに使います
利用者が開けない場合は、その人のメールアドレスと 403 画面に出た IP	利用者が「アクセスできません」と言う

アプリのソースコードやシークレットの値は送らないでください。必要になれば、こちらから範囲を指定して依頼します。

料金・契約・請求書についての問い合わせも同じ窓口です（料金と契約の運用）。