トラブルシューティング
よくある問題と解決方法をまとめています。
デプロイ関連
ビルドが失敗する
症状: デプロイ後、ステータスが「error」になる
確認方法: 1. アプリ詳細画面の「デプロイ履歴」タブを開く 2. 失敗したデプロイを選択してログを確認
よくある原因と対策:
| 原因 | 対策 |
|---|---|
| 依存関係のインストールエラー | package.json や go.mod などの依存関係ファイルを確認 |
| ビルドコマンドのエラー | プリデプロイコマンドを確認。ローカルで同じコマンドが動作するか確認 |
| Node.js バージョンの不一致 | package.json の engines フィールドでバージョンを指定 |
| メモリ不足 | スペックを上げる（Free プランでは Nano 固定） |
Node.js の例:
{
"engines": {
"node": ">=18.0.0"
}
}
ヘルスチェックが失敗する
症状: ビルドは成功するが、アプリが「running」にならない
確認方法: 1. ヘルスチェックエンドポイントが正しいか確認 2. アプリログでエラーを確認
よくある原因と対策:
| 原因 | 対策 |
|---|---|
| エンドポイントが存在しない | /health などのエンドポイントを実装する |
| ポートが異なる | 環境変数 PORT を使用してリッスンする |
| 起動に時間がかかる | 起動処理を最適化する |
例（Node.js）:
const PORT = process.env.PORT || 3000;
app.get('/health', (req, res) => {
res.status(200).json({ status: 'ok' });
});
app.listen(PORT, '0.0.0.0', () => {
console.log(`Server running on port ${PORT}`);
});
例（Go）:
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte(`{"status":"ok"}`))
})
http.ListenAndServe("0.0.0.0:"+port, nil)
再デプロイしても変更が反映されない
確認事項:
- 正しいブランチに push したか
- ビルドが成功しているか（デプロイ履歴を確認）
- ブラウザのキャッシュをクリア
データベース関連
データベースに接続できない
確認方法: 1. データベースのステータスが「running」か確認 2. 接続情報（URL、ホスト、ポートなど）が正しいか確認
よくある原因と対策:
| 原因 | 対策 |
|---|---|
| 環境変数が設定されていない | アプリの設定でデータベースを接続する |
| データベースが起動中 | 数分待ってから再試行 |
| 接続数の上限 | 接続プールを使用し、接続数を制限する |
接続がタイムアウトする
原因: アイドル接続が長時間続くとタイムアウトされる
対策: - 接続プールを使用する - 接続のキープアライブを設定する - リトライロジックを実装する
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 10,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
CLI 関連
「not logged in」エラー
原因: 認証されていない、またはトークンが期限切れ
対策:
kamui login
「session expired」エラー
対策:
kamui logout
kamui login
ブラウザが自動で開かない
対策: ターミナルに表示される URL を手動でブラウザにコピー＆ペースト
「project not found」エラー
確認事項:
1. プロジェクト名または ID が正しいか
2. kamui projects list で確認
静的サイト関連
「index.html が見つからない」エラー
原因: 指定したディレクトリに index.html がない
対策:
- ビルド出力ディレクトリを確認（dist、build など）
- ローカルでビルドを実行して出力を確認
SPA でリロードすると 404 になる
原因: サーバーサイドルーティングが設定されていない
対策: Kamui Platform では、SPA の場合に自動的に index.html にフォールバックします。
パフォーマンス関連
アプリが遅い
確認事項: 1. スペックが適切か（CPU、メモリ） 2. データベースクエリが最適化されているか 3. 外部 API 呼び出しがボトルネックになっていないか
対策: - スペックを上げる - データベースインデックスを追加 - キャッシュを導入
メモリ不足（OOM）
症状: アプリが突然停止する、再起動を繰り返す
対策: 1. スペックを上げる 2. メモリリークがないか確認 3. 一度に処理するデータ量を減らす
その他
問題が解決しない場合
- ログを確認: アプリログ、デプロイログで詳細なエラー情報を確認
- ダッシュボードを確認: ステータスや設定を再確認
- 再デプロイ: 一時的な問題の場合、再デプロイで解決することがある