SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor ・更新日 2026-10-13

systemd unitの終了コードを読む方法

systemctl statusを最初に確認し、203/EXECと226/NAMESPACEの意味を解説します。正常起動後、1秒で終了するunitの原因も確認できます。

systemd unit が起動しない理由

起動しない systemd unit では、失敗の理由が 1 つのフィールドに示されます。systemctl status <unit> を実行し、失敗を報告している行の code= と status= を確認します。200 番台のステータス番号は、ほとんどの場合、systemd がプログラムの実行に到達していないことを示します。unit file で指定された環境の構築中に失敗しています。ステータスが 200 未満で、行に code=exited と表示される場合は、プログラムが実行され、自身で終了しています。この場合、unit file は正しく、問題はアプリケーション側にある可能性が高いです。code=killed はシグナルによってプロセスが終了したことを示します。これは別のケースで、末尾付近で説明します。

この区分が判断の基準です。以下では、この区分に従い、番号が現れる順に説明します。

質問に順番どおり答える3つのコマンド

systemctl status myapp.service
journalctl -u myapp.service -b --no-pager
systemd-analyze verify /etc/systemd/system/myapp.service

systemctl status で判定します。まず Loaded: の行を読みます。この行には、systemd が実際に解析したファイルと、unit が有効化済みか、マスクされているか、まったく見つからないかが示されます。次に Active: の行を読み、その下にある code= と status= の組み合わせを確認します。

journalctl -u myapp.service -b --no-pager で詳細を確認します。-u は対象の unit だけに絞り、-b は今回のブートに限定するため、先週の障害ログを読むことがありません。--no-pager は端末へ直接出力するため、grep へパイプできます。status は最後の数行だけを表示し、長い行を短縮します。journal には、プログラムが停止する前に出力した内容がすべて残ります。通常、そこに本当のエラーがあります。-n を付けないと、このブート以降のすべてのエントリが表示されます。-n 100 を追加すると最新の 100 件だけに絞れます。または、別の端末で -f を実行しながら unit を再起動します。

systemd-analyze verify は unit ファイルを実行せずに読み込みます。未知のセクションやディレクティブを警告し、実行できない ExecStart= 内のコマンドも指摘します。これにより、気付きにくい2種類のミスを検出できます。1つはキーのスペルミスです。systemd は読み込み時に警告を出して無視しますが、多くの人はその警告を確認しません。もう1つは、存在しないパスです。

unit ファイルを編集した後は、sudo systemctl daemon-reload を実行します。これを実行するまで、systemd は以前に読み込んだコピーを使い続けます。また、systemctl status により、ディスク上のファイルが変更されているという警告も追加されます。「何も変わらなかった」修正は、systemd がまだ読み込んでいない修正であることがよくあります。

さらに2つのコマンドも使用します。systemctl cat myapp.service は有効な unit 定義を表示します。これはメインファイルに加え、/etc/systemd/system/myapp.service.d/ 配下のすべての drop-in を含む内容です。systemctl show myapp.service -p ExecStart -p User -p WorkingDirectory は、systemd が解析した値を表示します。実際に実行されるのはこの内容です。

status=203/EXEC は何を意味しますか?

203/EXEC は、systemd がセットアップを完了して execve() を呼び出したものの、kernel に拒否されたことを示します。プログラムは自身のコードを1行も実行していません。原因のほとんどは、次の4つに分類できます。

  1. ExecStart= のパスが誤っているか、絶対パスではありません。unit ファイル内の正確な文字列と ls -l の結果を照合してください。
  2. ファイルに execute ビットがありません。sudo chmod +x /opt/myapp/run.sh で修正できます。アーカイブから展開したファイルや別のマシンからコピーしたファイルでは、このビットが失われていることがあります。
  3. shebang 行が壊れています。kernel はスクリプトの1行目を読み、そこに指定された interpreter を実行します。そのため、サービスの PATH に python3 がないと #!/usr/bin/env python3 は失敗します。また、Windows の改行コードで保存されたファイルは /bin/bash\r という名前の interpreter を要求しますが、その interpreter は存在しません。
  4. ファイルがこのマシンで実行できる形式ではありません。architecture が違うか、shebang のないテキストファイルです。

変更を加える前に、サービスユーザーとして手動で実行し、同じ状態を再現してください。

sudo -u appuser /opt/myapp/run.sh
file /opt/myapp/run.sh
head -1 /opt/myapp/run.sh | cat -A

file は architecture を示し、改行コードが問題の場合は「CRLF line terminators」と報告します。cat -A でも、末尾に ^M があることを確認できます。sed -i 's/\r$//' /opt/myapp/run.sh で削除してください。

終了コードの範囲については、1つ注意が必要です。200以上を systemd 用とするのは慣例であり、保証ではありません。プログラム自身が203で終了することもでき、systemd は両者を区別できません。systemd-analyze exit-status 203 は任意のコードの名前とクラスを表示するため、表の読み取りに役立ちます。ただし、アプリケーションが199を超える終了コードを使用する場合は、コードを変更してください。

217/USER または 216/GROUP になるのはなぜですか?

217/USER は通常、User= に指定されたアカウントがサービスの起動時点で存在しないことを示します。同じコードは、PrivateUsers= などのサンドボックス機能でユーザー名前空間の設定に失敗した場合にも返されます。この場合、journal には存在しないユーザー名ではなく、"Failed to set up user namespacing" と記録されます。216/GROUP は、Group= または SupplementaryGroups= に対して発生する同じ失敗です。それぞれ、1 つのコマンドで確認できます。

getent passwd appuser
getent group appgroup

各コマンドは行を出力するか、何も出力せずに 0 以外の終了ステータスを返します。何も出力されない場合、その名前はシステムに登録されていません。そのため、systemd はそのアカウントに切り替えられず、exec の前に停止します。対処方法はアカウントを作成することです。User=root を設定することではありません。1 つのサービスを 最小権限の専用システムアカウントで実行することが、このディレクティブの目的です。

sudo useradd --system --no-create-home --shell /usr/sbin/nologin appuser

DynamicUser=yes を使うと、起動ごとに systemd が一時アカウントを割り当てるため、この問題を回避できます。状態を保持しないサービスに適しています。ファイルを書き込むサービスでは、StateDirectory= も併用する必要があります。起動ごとにユーザー ID が変わるため、通常のパスにあるファイルが、すでに存在しないアカウントの所有になるためです。

226/NAMESPACE とは何ですか?

226/NAMESPACE は、サンドボックス化のディレクティブに起因します。unit で ProtectSystem=、ProtectHome=、PrivateTmp=、ReadWritePaths= などを設定すると、systemd はプログラムを exec する前に、そのサービス用のプライベートな mount namespace を作成します。ここでいう namespace は、1 つのプロセスから見えるファイルシステムの専用ビューです。その構成に含まれる mount のいずれかが失敗すると、起動は 226 で失敗し、プログラムは実行されません。

通常の原因は、ReadWritePaths= 内のパスが存在しないことです。ProtectSystem=strict はファイルシステム全体を read only で mount し、ReadWritePaths= は指定したパスを再び write 用に開きます。systemd は存在しないディレクトリを再び開くことができません。適切な修正方法は 2 つあります。StateDirectory= で systemd にディレクトリを作成させます。これにより、systemd は起動のたびに /var/lib/<name> を作成し、サービスユーザーに割り当てます。または、パスの先頭に - を付けます。これにより、ソースが存在しない場合に systemd はそのエントリを無視します。ハードニングを削除するのは適切ではありません。5 分の問題と引き換えに、恒久的な問題を招くためです。

[Service]
ProtectSystem=strict
ProtectHome=yes
StateDirectory=myapp
ReadWritePaths=-/srv/uploads

どの行が原因か分からない場合は、ハードニングのブロック全体を削除し、reload してから start します。サービスが起動した場合は、行を 1 つずつ戻し、その都度 restart します。この系統で近いエラーには 233/RUNTIME_DIRECTORY と 238/STATE_DIRECTORY があります。これらは、RuntimeDirectory= または StateDirectory= に指定されたディレクトリを systemd が作成できなかったか、所有権を設定できなかったことを示します。通常は、そのパスがすでに存在し、別のユーザーに属していることが原因です。

WorkingDirectory が正しいように見えるのに、なぜ 200/CHDIR と表示されるのですか?

200/CHDIR は、WorkingDirectory= への chdir() に失敗したことを示します。ディレクトリが存在しないか、サービスユーザーがそのディレクトリに入れません。ディレクトリに入るには、そのディレクトリと、上位にあるすべての親ディレクトリに対する実行権限が必要です。そのため、/home/deploy/app が完全に読み取り可能でも、/home/deploy のモードが 700 で、サービスが appuser として実行されている場合は到達できません。

sudo -u appuser test -x /srv/myapp && echo ok
namei -l /srv/myapp

namei -l は、パスを構成する各要素の所有者とモードを表示します。どのディレクトリが後続の要素へのアクセスを妨げているかを、最も速く特定できます。WorkingDirectory=-/srv/myapp と記述すると、ディレクトリが存在しなくてもエラーになりません。開始場所を問わないプログラムには適していますが、相対パスでファイルを開くプログラムには適していません。

サービスが起動してから 1 秒後に停止するのはなぜですか?

ここでは 200 系のコードがなく、エラーテキストも表示されないことがよくあります。unit は起動直後に inactive (dead) を示すか、activating (auto-restart) を繰り返します。systemd は環境を正しく構築しています。問題は、プログラムの動作と Type= が想定する動作の不一致です。

デフォルトの Type=simple は、プログラムがフォアグラウンドで動作し続けることを示します。バックグラウンドへ fork して終了する daemon を指定すると、systemd はメインプロセスの終了を検知し、サービスが完了したと判断します。多くの daemon には、フォアグラウンドで動作し続けるための nginx -g 'daemon off;' のようなフラグがあります。

Type=forking は、子プロセスの準備が完了すると最初のプロセスが終了することを示します。フォアグラウンドで動作するプログラムを指定すると、start ジョブは TimeoutStartSec= が終了するまで待機します。デフォルトでは 90 秒後に systemd がプロセスを強制終了し、タイムアウトをログに記録します。

Type=notify は、プログラムが sd_notify() を呼び出して準備完了を通知することを示します。この機能に対応していないプログラムは何も通知しないため、起動がタイムアウトし、journal にはプロトコルエラーとして結果が記録されます。

プログラムの実際の動作に応じて type を選択します。simple、forking、oneshot、notify の違いを確認すれば、この種の障害に対する判断を解決できます。

サービスが何度も終了すると、systemd は試行を停止し、起動要求が短時間に繰り返されたと報告します。その後 unit は failed 状態のままとなり、systemd は自動的に再起動しません。レート制限の間隔が経過すれば手動で起動できます。または sudo systemctl reset-failed myapp.service を実行すると、failed 状態と再起動カウンターがクリアされ、すぐに手動起動できるようになります。制限値を引き上げても、症状が隠れるだけです。最後の失敗ではなく最初の失敗から journal を確認し、変更する前にRestart=on-failure が実際に再試行する内容を確認してください。

エラーがないのに unit が inactive なのはなぜですか?

unit は起動されずにスキップされることがあります。Condition* ディレクティブは、意図的にメッセージを出しません。チェックに失敗すると、systemd はジョブを成功として扱い、何もしません。ConditionPathExists=/etc/myapp/config.yml を持つ unit は、そのファイルが存在しない間は起動しません。また、エラーも報告しません。

systemctl show myapp.service -p ConditionResult -p ConditionTimestamp
journalctl -u myapp.service -b --no-pager | grep -i condition

ConditionResult=no でスキップを確認できます。journal には、成立しなかったチェックの内容が記録されます。前提条件がない場合に明示的に失敗させるには、代わりに Assert* ディレクティブを使用します。Conditions、asserts、unit の順序では、各チェックをどこに指定すべきかを説明しています。

この付近には、他にも静かに処理されるケースがあります。「could not be found」エラーは、通常、ファイルが誤ったディレクトリにあるか、reload を実行していないことを示します。作成した unit ファイルは /etc/systemd/system/ に配置します。masked unit は、sudo systemctl unmask myapp.service で解除するまで、どのような起動も拒否します。また、systemctl enable は [Install] セクションがない unit では失敗します。そのため、WantedBy=multi-user.target を指定してください。

失敗したのではなく、強制終了された場合はどうしますか?

code=killed は code=exited とは別の問題です。プロセスの外部から、何者かがプロセスを終了させています。status=9/KILL は多くの場合、out of memory(OOM)killer を示します。その場合、journal には選択されたプロセスが記録されます。ただし、SIGKILL だけでは誰が送信したかは分かりません。停止中のサービスが TimeoutStopSec= を超えても SIGTERM を無視すると、systemd も SIGKILL を送信します。そのため、メモリを疑う前に、停止または再起動が実行中だったかを確認してください。自分で設定した制限でも、cgroup(control group)内では同じようにプロセスが強制終了されます。そのため、free -m でホストの空きメモリを確認し、unit に MemoryMax= が設定されていないか調べてください。MemoryMax、CPUQuota などの cgroup 制限では、プロセスを終了させる制限と、処理を遅くするだけの制限について説明しています。

起動を試みた直後の status=15/TERM は、通常、systemd が起動処理をタイムアウトさせ、プロセスを終了したことを示します。この場合は Type= に戻って確認します。

これらの障害の大半を防ぐ 2 つの習慣

常に絶対パスを使用します。 systemd はログインシェルを起動しないため、.bashrc も .profile もなく、仮想環境も有効化されていません。システムサービスの $PATH は、/opt や言語バージョンマネージャーの shim を含まない、短い組み込みリストです。/usr/bin/python3 または /opt/myapp/venv/bin/python を完全なパスで記述します。シェルで command -v myapp を実行すると、貼り付けるパスが表示されます。同じルールは WorkingDirectory=、EnvironmentFile=、ReadWritePaths= 内のすべてのパスにも適用されます。

ExecStart= はシェルではありません。 systemd は行を単語に分割し、execve() 自体を呼び出します。パイプ、リダイレクト、glob、&&、バッククォート、~ には意味がありません。これらはリテラル引数としてプログラムに渡されます。ExecStart=/usr/bin/myapp --flag > /tmp/out.log は > と /tmp/out.log を myapp に渡します。その後、myapp は usage エラーで終了するため、systemd の問題とは思えない形で現れます。シェル機能が必要な場合は、シェルを明示的に呼び出します。

ExecStart=/bin/sh -c '/usr/bin/myapp --flag | /usr/bin/tee -a /var/log/myapp.log'

出力だけが必要な場合は、シェルを使う必要はありません。サービスの出力はデフォルトで journal に送られ、StandardOutput=append:/var/log/myapp.log はシェルを介さずにファイルへ書き込みます。

変数展開にも同じ制限があります。$MYVAR と ${MYVAR} は Environment=、EnvironmentFile=、および $USER など systemd 自身が設定する少数の変数から置き換えられます。% のような specifier も %i のように展開されます。ログインシェルの変数は展開されません。$HOME は unit に User= がある場合に限り、SetLoginEnvironment= のデフォルトを通じて設定されます。そのため、User= のない root 実行のサービスには、明示的に設定しない限り $HOME がありません。EnvironmentFile= もシェルスクリプトではありません。export はその中では使用できず、引用符の規則も bash とは異なります。また、- をパスの先頭に付けない限り、ファイルが存在しないと致命的なエラーになります。

稼働中のサーバーで切り分ける

コードを読み、原因を実証し、1 つだけ変更して、再起動します。この順序は、すべての数値を把握していることより重要です。推測に基づく変更を 3 つ重ねて、どの変更が効果をもたらしたのか分からなくなる事態を防げるためです。自分で作成していない unit にも、同じ手順を適用できます。動作しない timer は、起動していない service です。まず service をデバッグしてください。systemd timer と、それが起動する service は、上記とまったく同じ原因で失敗します。timer が出力を隠すため、journal に出力を要求するまで内容を確認できません。

FAQ

systemctl status で status=203/EXEC と表示されるのはなぜですか?

systemd は unit が要求した設定をすべて適用しましたが、execve() の呼び出しに失敗したため、プログラムは起動していません。次の4点を順に確認してください。ExecStart= に指定したパスが存在し、絶対パスであること。ファイルに実行ビットが付いていること。shebang が、service の PATH 上に存在するインタープリターを指定していること。ファイルの改行コードが Unix 形式であることです。最後の点については、file が "with CRLF line terminators" と報告します。この場合、インタープリター名が /bin/bash\r になり、kernel が実行を拒否します。

サービスが起動した直後に停止するのはなぜですか?

unit ファイルが、プログラムにはない動作を前提にしています。Type=simple では systemd はプログラムがフォアグラウンドで動作し続けることを想定します。そのため、daemon が fork してバックグラウンドへ移ると、fork した時点で終了したように見えます。Type=forking では systemd は最初のプロセスが終了するまで待つため、フォアグラウンドのプログラムでは TimeoutStartSec= が尽きるまで start job が終了しません。Type= をプログラムの動作に合わせてください。プログラムにフォアグラウンド用の flag がある場合は、デフォルトの Type=simple と組み合わせて使用します。

短い status 出力ではなく、実際のエラーを確認するにはどうすればよいですか?

systemctl status は journal の末尾数行だけを表示し、長い行を途中で切り詰めます。journalctl -u myapp.service -b --no-pager を実行すると、この boot 中に unit が記録したすべての内容を取得できます。-n 200 を追加すると最新の 200 行だけに絞り込めます。または grep へ pipe してください。アプリケーションが独自の log ファイルに書き込む場合は、そのファイルも確認してください。systemd が取得するのは、プログラムが standard output と standard error に送った内容だけだからです。

エラーメッセージがないのに unit が inactive になるのはなぜですか?

最も多い原因は、Condition* directive によって起動がスキップされたことです。これらのチェックは何も表示しません。condition に失敗しても、start job は成功として扱われます。systemctl show myapp.service -p ConditionResult を実行して ConditionResult=no を探し、チェック内容を示す journal の行を確認してください。もう1つの一般的な原因は masked unit です。この unit は sudo systemctl unmask で解除するまで、すべての起動要求を拒否します。

unit ファイルを変更するたびに daemon-reload は必要ですか?

unit ファイルまたは drop-in を編集した場合は必要です。sudo systemctl daemon-reload により systemd はディスク上のファイルを再読み込みし、sudo systemctl restart myapp.service で実行中の service に適用します。systemctl edit の後は必要ありません。この操作が自動的に再読み込みを行うためです。systemd ではなくアプリケーションに属する設定ファイルを変更した場合も必要ありません。

この記事は役に立ちましたか?

#systemd#troubleshooting#journalctl#exit-codes#linux-fundamentals