CHAPTER 09 / KOHAKU
トラブルシュート
症状から確認先をたどります。最初の原因をログで特定し、設定・配備・接続のどこで失敗したかを切り分けます。
最初に記録するもの
配布ディレクトリ、JDK版、起動方法、変更した設定、対象URL、HTTPステータス、応答のX-Request-Idを記録します。設定ファイルやログを共有する際はパスワード・資格情報・SQLリテラルを伏せてください。
配布ディレクトリで実行
"${KOHAKU_JAVA_HOME:-/opt/java/jdk21}/bin/java" -version
cat logs/kohaku.pid
curl -i http://127.0.0.1:9090/health/ready
tail -n 100 logs/kohaku.outPIDファイルや管理ポートは設定・起動方法によって存在しません。runでは起動したターミナル、targetを指定した構成ではコンテナログのファイルも確認します。起動バナーで今回の起動試行を見分け、後始末の警告より前に出た最初のERRORを確認します。
症状別の確認
| 症状 | 確認・対処 |
|---|---|
| 起動スクリプトがJDKを見つけない | KOHAKU_JAVA_HOME/bin/javaの実在と実行権限。ビルドラッパーは別途 /opt/java/jdk21 を固定参照 |
| 起動時の設定エラー | エラーにあるファイル・キーを確認。UTF-8、インデント、重複、TRUE等の禁止表記、数値の範囲を設定章で照合 |
| BindException / 接続できない | http.port / https.port / management.portの重複と他プロセスの占有を確認。listenするhostと実際のアクセス先も一致させる |
| TLS設定後に起動しない | https.portとkeyStoreの両方、JKS形式、読取権限、鍵とストアのパスワード、clientAuthとtrustStoreの組合せを確認 |
| startは成功したがURLが応答しない | startは生存確認だけ。readinessとアプリURLを別々に確認し、起動中のログを見る |
| ルートURLが404 | 既定でROOTアプリは置かれない。/hello/等のコンテキストパスを確認。ROOT.warを置く場合は大文字にする |
| アプリだけ404 / 配備できない | 配備失敗ログ、web.xml/fragment/annotationの競合、kohaku-web.xmlの名前空間・version・新要素名、JNDI定義・ドライバを確認 |
| WAR更新が反映されない | hotdeploy.enabled、mtime/サイズ、同名ディレクトリ優先を確認。展開ディレクトリ編集は自動再配備しない |
| JSPが500 | JDK（jdk.compiler）で起動しているか、WEB-INF/tmpの書込権限、JSP翻訳エラーとTLD/taglib解決を確認 |
| FORMログインだけ403 | Origin/Refererが欠落・null・不正ではないか。公開名/ポート、canonical-authority、プロキシの転送条件を認証章で確認 |
| セッションが続かない | ブラウザのCookie、path、Secure、SameSiteを確認。URL追跡は既定で無効。URL追跡宣言で配備失敗していないかも確認 |
| リクエストが413 / 408 | 本文サイズとread・絶対期限を区別する。無条件に上限を拡大せず、正当な要求のサイズ・時間を把握する |
| getParameterが例外 | http.maxParameterCountの超過と、アプリが送ったパラメータ個数を確認 |
| JNDI lookupに失敗 | webapp実行コンテキストか、java:comp/envからの相対名、resource-refの型、local/共有定義の優先と名前重複を確認 |
| DB接続を借りられない | close漏れ、maxConnections/maxIdle、DB/ドライバの期限、停滞接続を確認。全枠停滞なら即時拒否される |
| JTA結果不明 / in-doubt | 対象トランザクションのincidentとDB側の状態を照合。永続リカバリログは無く、業務処理の無条件再実行は避ける |
| WebSocketが503 / closeされる | HTTPとWS接続枠、1009のサイズ上限、1008のレート上限、idleとsend期限を設定表で確認 |
| 管理面にアクセスできない | management.portの明示設定と再起動を確認。既定は無効、hostは127.0.0.1。アプリのポートにはhealthパスがない |
| readinessがUPなのにアプリが失敗 | 現行readinessは個別webapp・DB・過負荷を判定しない。必要なアプリの業務疎通を別に実行 |
| アクセスログが出ない | accesslog.enabled（既定false）、出力先の書込権限。開けなければWARNして無効のまま続行する |
| ログが回らない | target=stderrではコンテナログrotationは無効。accesslog.rotateとlogging.yamlのrotateを区別。kohaku.outは対象外 |
| 停止が失敗 / 期限超過 | PIDとnonceの照合エラーか、停止処理の停滞かを分ける。期限超過は自動SIGKILLしない。--forceは照合を省略するだけ |
| tempが増える / quarantine警告 | 停止できない処理や回収失敗で旧世代が残り得る。プロセスとDBの残存資源を確認し、稼働中の作業領域を削除しない |
再試行の前に
まず原因となった設定や配備物を直し、起動ログ・readiness・実アプリの応答で結果を確認します。クエリやトランザクションの結果が不明な場合は、業務データ側を確認してから再実行を判断します。未解決の実行やDB接続を、単なる警告として読み飛ばさないでください。