こんにちは！現場で毎日コードと向き合っていると、避けて通れないのが「あれ、なんでCI（継続的インテグレーション）が急に赤くなってるの？」という絶望的な瞬間ですよね。
特にJenkinsを使っていると、謎のエラーコードや真っ赤なログに冷や汗をかいた経験、誰しも一度はあるはずです。
今回は、Jenkinsのビルドが失敗したときに、慌てず騒がず秒速で原因を特定し、元の緑色（成功）の世界へ連れ戻すための「トラブルシューティング完全マニュアル」を授けましょう。これをマスターすれば、毎日の作業が劇的に楽になりますよ。
—
1. まず敵を知る：よくあるエラーコード（403, 503など）の正体と対策
Jenkinsを動かしていると、ブラウザやコンソールログに冷酷な数字が表示されます。まずは、この数字の意味と、それぞれの華麗なかわし方を覚えましょう。
① HTTP 403 Forbidden （アクセス拒否・CSRF対策エラー）
- どんなときに出る？
外部のスクリプトからAPIを叩いたときや、プラグインの連携設定をしているときに突然現れます。「お前、誰だ！」とJenkinsの門番に追い払われている状態です。
- 原因と対策:
現代のJenkinsは、セキュリティ（CSRF保護）が非常に厳格になっています。
- 対策A: Jenkinsのシステム設定（`Manage Jenkins` > `Security`）で、「Prevent Cross Site Request Forgery exploits」のチェックを外すのはセキュリティ上有害なので厳禁です。
- 対策B: APIや外部ツールから叩く場合は、ユーザーの「APIトークン」を発行し、Basic認証ヘッダーに正しく含めるようにしてください。
② HTTP 503 Service Unavailable （サービス利用不可・過負荷）
- どんなときに出る？
Jenkinsの起動直後や、重いビルドを同時に何個も走らせたときに、画面が真っ白になってこのエラーが出ます。
- 原因と対策:
大抵の場合、Jenkinsの本体（Javaプロセスのヒープメモリ）が力尽きています。
- 対策: Jenkinsをホストしているサーバーにログインし、JVMのメモリ割り当て（`-Xmx`オプションなど）を増やしましょう。また、不要なビルド履歴が溜まりすぎてファイルシステムが悲鳴を上げているケースも多いです。
③ 127 / 137 / 143 などの謎の終了コード（シェルスクリプト実行時）
- どんなときに出る？
「Execute shell」などでビルドスクリプトを書いた際、理由もわからずビルドが途中でプツッと途切れます。
- 原因と対策:
- 終了コード `137`: これはLinuxのOOM Killer（Out of Memory Killer）の仕業です。テストやビルド（Dockerビルドやnpm installなど）がメモリを喰らい尽くし、OSに強制終了させられています。スワップ領域を作るか、マシンのスペックを上げましょう。
- 終了コード `127`: コマンドが見つからないエラーです（例: `git`や`docker`コマンドのパスがJenkinsユーザーに通っていない）。
—
2. ワークスペースの「呪い」を解く！クリーンアップの奥義
「ローカルの俺のPCでは動くのに、なぜJenkinsだとファイルが見つからないと言われるんだ……？」
これはCI/CDエンジニアが発するセリフランキング第1位です。
Jenkinsは、前回のビルドで使用したファイルを「ワークスペース」に残し続けます。これが原因で、古いキャッシュが悪さをしたり、Gitのコンフリクトが置き去りになったりします。
処方箋：ワークスペースを強制的に綺麗にする
迷ったら、まずはワークスペースをまっさらにしましょう。
1. GUIから手動で消す場合:
該当ジョブのメニューから 「Workspaceの削除 (Wipe Out Workspace)」 をポチッと押すだけです。これだけで大半の怪奇現象は消え去ります。
2. パイプライン（Jenkinsfile）で自動化する場合:
毎回クリーンな状態でビルドを始めたいなら、`Jenkinsfile` の最初に次の一行を仕込みましょう。
pipeline {
agent any
options {
// ビルド開始時にワークスペースを綺麗さっぱりお掃除
ansiColor(‘xterm’)
timeout(time: 1, unit: ‘HOURS’)
skipDefaultCheckout() // デフォルトのチェックアウトをスキップして制御を握る
}
stages {
stage(‘Clean Workspace’) {
steps {
// ゴミファイルを完全に消し去る
cleanWs(deleteDirs: true, notFailBuild: true)
}
}
stage(‘Checkout’) {
steps {
checkout scm
}
}
}
}
この `cleanWs` プラグインを使ったレシピを仕込んでおくだけで、「ファイル競合の呪い」から永遠に解放されます。
—
3. 名探偵になれ！「ログ」から真犯人を炙り出すヒント
ビルドが失敗したとき、赤い文字がバーっと並んでどこを見ればいいか分からなくなりますよね。ログを効率よく読み解くための3つの目を養いましょう。
ヒント①：「最初にエラーが出た行」を探す
人間は一番下の「BUILD FAILURE」という結果に目が行きがちですが、本当に重要なのはエラーの連鎖の「一番上（最初にコケた場所）」です。
下の方にあるエラーは、最初のエラーに引きずられて起きた「二次災害」であることがほとんどです。
ヒント②：ログの出力レベルを上げる（Log Recorder）
「何が起きているのかもっと詳しく知りたい！」というときは、Jenkinsの「システムログ（Log Recorder）」を活用します。
1. `Manage Jenkins` > `System Log` に移動。
2. 新しいログレコーダーを追加（例: `Git` や `Com.cloudbees.jenkins` など）。
3. ログレベルを `ALL` または `FINE` に設定。
これで、裏側でJenkinsがGitや外部ツールとどんな会話をしているのかが丸見えになります。
ヒント③：環境変数をダンプして世界を知る
「なぜかパスが通っていない」「変数が取れない」というときは、ビルドの最初に環境変数をすべて出力してみましょう。
- Freestyleプロジェクトの場合:
ビルド手順に「Execute shell」を追加し、`env` とだけ打って実行します。
- Declarative Pipelineの場合:
stage(‘Debug Env’) {
steps {
sh ‘printenv’
}
}
これで、Jenkinsという「隔離された世界」で何が見えているのかが一発でわかります。
—
まとめ：失敗を恐れるな、ログは語る
Jenkinsのビルドエラーは、あなたを困らせるために起きているのではありません。「ここを直してほしいんだよ」というJenkinsからのラブレター（あるいはSOS）です。
1. エラーコードを見たら、まずは権限やメモリを疑う
2. 怪しいときは迷わずワークスペースを消してリセットする
3. ログは「最初のエラー」を上から探す
この3つのステップを頭に入れておけば、どんなに難解なビルドエラーに直面しても、冷静に、かつスマートに解決できるようになります。
さあ、エラーを怖がるのはもうおしまい。今日も快適な自動化ライフを楽しみましょう！