SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor · Aktualisiert 2026-11-13

systemd-Unit startet nicht: Exit-Code richtig lesen

Prüfen Sie zuerst systemctl status: Was 203/EXEC und 226/NAMESPACE bedeuten und warum eine Unit sauber startet, aber eine Sekunde später endet.

Warum eine systemd-Unit nicht startet

Eine systemd-Unit, die nicht startet, nennt den Grund in einem Feld. Führen Sie systemctl status <unit> aus und suchen Sie in der Zeile mit der Fehlermeldung nach code= und status=. Eine Statusnummer im Bereich der 200 bedeutet fast immer, dass systemd Ihr Programm nicht erreicht hat: Der Aufbau der Umgebung, die Ihre Unit-Datei angefordert hat, ist fehlgeschlagen. Wenn die Zeile bei einem Status unter 200 code=exited meldet, wurde Ihr Programm ausgeführt und anschließend selbst beendet. Die Unit-Datei ist dann wahrscheinlich korrekt, aber die Anwendung nicht. code=killed bedeutet, dass ein Signal den Prozess beendet hat. Dieser separate Fall wird weiter unten behandelt.

Diese Unterscheidung gibt den Entscheidungsweg vor. Alles Folgende ergibt sich daraus und folgt der Reihenfolge, in der die Nummern auftreten.

Welche drei Befehle beantworten die Frage in dieser Reihenfolge

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

systemctl status liefert das Ergebnis. Lesen Sie zuerst die Zeile Loaded:, weil sie den Dateipfad nennt, den systemd tatsächlich eingelesen hat, und angibt, ob die Unit aktiviert, maskiert oder überhaupt nicht gefunden wurde. Lesen Sie danach die Zeile Active: sowie das darunterstehende Paar code= und status=.

journalctl -u myapp.service -b --no-pager liefert die Details. -u filtert auf diese eine Unit, -b beschränkt die Ausgabe auf den aktuellen Bootvorgang, damit Sie keinen Fehler aus der vergangenen Woche lesen, und --no-pager gibt die Ausgabe direkt im Terminal aus, sodass Sie sie an grep weiterleiten können. status zeigt nur die letzten paar Logzeilen und kürzt lange Zeilen. Das Journal zeigt alles, was das Programm vor dem Abbruch ausgegeben hat. Das ist normalerweise der eigentliche Fehler. Ohne -n erhalten Sie jeden Eintrag aus diesem Bootvorgang. Fügen Sie -n 100 hinzu, um nur die letzten 100 Einträge zu behalten, oder führen Sie den Befehl mit -f in einem zweiten Terminal aus, während Sie die Unit neu starten.

systemd-analyze verify lädt eine Unit-Datei, ohne sie auszuführen. Der Befehl warnt vor unbekannten Abschnitten und Direktiven und kennzeichnet Befehle in ExecStart=, die er nicht ausführen kann. Damit werden die beiden unauffälligen Fehlerklassen erkannt: ein falsch geschriebener Schlüssel, den systemd beim Laden mit einer Warnung ignoriert, die die meisten Benutzer nie lesen, und ein nicht vorhandener Pfad.

Führen Sie nach dem Bearbeiten einer Unit-Datei sudo systemctl daemon-reload aus. Bis dahin verwendet systemd weiterhin die zuvor geladene Kopie, und systemctl status fügt eine Warnung hinzu, dass sich die Datei auf dem Datenträger geändert hat. Eine Änderung, die „nichts bewirkt“ hat, wurde von systemd häufig noch nicht eingelesen.

Zwei weitere Befehle sind ebenfalls wichtig. systemctl cat myapp.service gibt die effektive Unit aus, also die Hauptdatei einschließlich aller Drop-ins unter /etc/systemd/system/myapp.service.d/. systemctl show myapp.service -p ExecStart -p User -p WorkingDirectory gibt diese Werte so aus, wie systemd sie eingelesen hat. Genau diese Konfiguration wird ausgeführt.

Was bedeutet status=203/EXEC?

203/EXEC bedeutet, dass systemd die Einrichtung abgeschlossen, execve() aufgerufen und der Kernel den Aufruf abgelehnt hat. Ihr Programm hat keine eigene Codezeile ausgeführt. Vier Ursachen decken fast alle Fälle ab.

  1. Der Pfad in ExecStart= ist falsch oder nicht absolut. Prüfen Sie ihn mit ls -l anhand der exakten Zeichenfolge in der Unit-Datei.
  2. Die Datei hat kein Ausführungsrecht. sudo chmod +x /opt/myapp/run.sh behebt das. Eine aus einem Archiv entpackte oder von einem anderen Rechner kopierte Datei verliert dieses Recht häufig.
  3. Die Shebang-Zeile ist fehlerhaft. Der Kernel liest die erste Zeile eines Skripts und startet den dort genannten Interpreter. Daher schlägt #!/usr/bin/env python3 fehl, wenn der Service-PATH kein python3 enthält. Eine Datei mit Windows-Zeilenenden fordert einen Interpreter namens /bin/bash\r an, der nicht existiert.
  4. Die Datei kann auf diesem Rechner nicht ausgeführt werden: Sie hat die falsche Architektur oder ist eine Textdatei ohne Shebang.

Führen Sie den Aufruf zuerst als Dienstbenutzer manuell aus, bevor Sie etwas ändern.

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

file nennt die Architektur und meldet "with CRLF line terminators", wenn die Zeilenenden das Problem verursachen. cat -A zeigt dasselbe als abschließendes ^M. Entfernen Sie diese Zeichen mit sed -i 's/\r$//' /opt/myapp/run.sh.

Ein wichtiger Hinweis zum Wertebereich: 200 und höher ist eine Konvention, keine Garantie. Ihr eigenes Programm kann mit 203 beendet werden, und systemd kann die beiden Fälle nicht unterscheiden. systemd-analyze exit-status 203 gibt den Namen und die Klasse eines beliebigen Codes aus. Das erleichtert das Lesen der Tabelle. Wenn Ihre Anwendung jedoch Exit-Codes über 199 verwendet, ändern Sie diese.

Warum erhalte ich 217/USER oder 216/GROUP?

217/USER bedeutet normalerweise, dass das in User= angegebene Konto beim Start des Dienstes nicht existiert. Derselbe Code gilt auch, wenn der User-Namespace für eine Sandboxing-Option wie PrivateUsers= nicht eingerichtet werden kann. In diesem Fall enthält das Journal die Meldung „Failed to set up user namespacing“, statt einen fehlenden Benutzer zu nennen. 216/GROUP bezeichnet denselben Fehler für Group= oder SupplementaryGroups=. Bestätigen Sie das jeweils mit einem Befehl.

getent passwd appuser
getent group appgroup

Jeder Befehl gibt entweder eine Zeile aus oder keine Ausgabe und einen Rückgabewert ungleich 0. Keine Ausgabe bedeutet, dass der Name dem System unbekannt ist. systemd kann nicht zu diesem Konto wechseln und beendet den Start vor exec. Die Lösung besteht darin, das Konto anzulegen, nicht darin, User=root zu setzen. Einen Dienst mit einem dedizierten Systemkonto mit den geringsten erforderlichen Rechten auszuführen, ist der eigentliche Zweck dieser Direktive.

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

DynamicUser=yes umgeht das Problem, indem systemd bei jedem Start ein temporäres Konto anlegt. Das eignet sich für einen Dienst, der keinen Zustand speichert. Alles, was Dateien schreibt, benötigt zusätzlich StateDirectory=, weil sich die Benutzer-ID zwischen den Starts ändert und Dateien unter einem einfachen Pfad dann einem Konto gehören, das nicht mehr existiert.

Was ist 226/NAMESPACE?

226/NAMESPACE entsteht durch die Sandbox-Direktiven. Wenn eine Unit ProtectSystem=, ProtectHome=, PrivateTmp=, ReadWritePaths= oder etwas Ähnliches setzt, erstellt systemd für diesen Dienst einen privaten Mount-Namensraum, bevor es das Programm mit exec startet. Ein Namensraum ist hier eine private Ansicht des Dateisystems für einen Prozess. Wenn ein Mount in diesem Plan fehlschlägt, schlägt der Start mit 226 fehl, und Ihr Programm wird nie ausgeführt.

Die häufigste Ursache ist ein Pfad in ReadWritePaths=, der nicht existiert. ProtectSystem=strict bindet das gesamte Dateisystem schreibgeschützt ein, und ReadWritePaths= öffnet benannte Pfade erneut zum Schreiben. systemd kann ein Verzeichnis nicht erneut öffnen, wenn es nicht vorhanden ist. Dafür gibt es zwei geeignete Lösungen. Lassen Sie systemd das Verzeichnis mit StateDirectory= erstellen. Dadurch wird /var/lib/<name> bei jedem Start angelegt und dem Dienstbenutzer zugewiesen. Alternativ stellen Sie dem Pfad - voran. Damit weist systemd den Eintrag zu ignorieren, wenn die Quelle fehlt. Die falsche Lösung besteht darin, die Härtung zu entfernen. Damit tauschen Sie ein fünfminütiges Problem gegen ein dauerhaftes ein.

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

Wenn Sie nicht feststellen können, welche Zeile verantwortlich ist, entfernen Sie den gesamten Härtungsblock, laden Sie die Konfiguration neu und starten Sie den Dienst. Wenn der Dienst startet, fügen Sie die Zeilen einzeln wieder hinzu und starten Sie den Dienst nach jeder Zeile neu. Zwei verwandte Fehler in dieser Gruppe sind 233/RUNTIME_DIRECTORY und 238/STATE_DIRECTORY. Sie bedeuten, dass systemd das in RuntimeDirectory= oder StateDirectory= angegebene Verzeichnis nicht erstellen oder dessen Besitz nicht übernehmen konnte. Die Ursache ist meist, dass dieser Pfad bereits existiert und einem anderen Benutzer gehört.

Warum erscheint 200/CHDIR, obwohl WorkingDirectory korrekt aussieht?

200/CHDIR bedeutet, dass chdir() nach WorkingDirectory= fehlgeschlagen ist. Das Verzeichnis fehlt, oder der Dienstbenutzer kann es nicht betreten. Zum Betreten eines Verzeichnisses ist das Ausführungsrecht für dieses Verzeichnis und für jedes übergeordnete Verzeichnis erforderlich. Daher ist ein vollständig lesbares /home/deploy/app nicht erreichbar, wenn /home/deploy den Modus 700 hat und der Dienst als appuser ausgeführt wird.

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

namei -l gibt Eigentümer und Modus jeder Komponente des Pfads aus. Das ist der schnellste Weg, das Verzeichnis zu finden, das den weiteren Zugriff blockiert. Wenn Sie WorkingDirectory=-/srv/myapp setzen, ist ein fehlendes Verzeichnis kein fataler Fehler. Das ist für ein Programm richtig, dem sein Startverzeichnis gleichgültig ist, und für ein Programm falsch, das Dateien über relative Pfade öffnet.

Warum startet der Dienst und beendet sich eine Sekunde später?

Hier gibt es keinen Code der 200er-Serie und häufig überhaupt keinen Fehlertext. Die Unit zeigt direkt nach dem Start inactive (dead) oder durchläuft wiederholt activating (auto-restart). systemd hat die Umgebung korrekt eingerichtet. Die Abweichung liegt zwischen dem Verhalten Ihres Programms und dem, was Type= zugesichert hat.

Type=simple, der Standardwert, bedeutet, dass das Programm im Vordergrund bleibt. Wenn Sie einen Daemon angeben, der in den Hintergrund forkt und sich beendet, erkennt systemd das Ende des Hauptprozesses und betrachtet den Dienst als beendet. Die meisten Daemons bieten eine Option, um im Vordergrund zu bleiben, beispielsweise nginx -g 'daemon off;'.

Type=forking bedeutet, dass sich der erste Prozess beendet, sobald sein Kindprozess bereit ist. Wenn Sie ein Vordergrundprogramm angeben, wartet der Startauftrag, bis TimeoutStartSec= abläuft. Das geschieht standardmäßig nach 90 Sekunden. Danach beendet systemd den Prozess und protokolliert einen Timeout.

Type=notify bedeutet, dass das Programm sd_notify() aufruft, um seine Bereitschaft zu melden. Ein Programm ohne diese Unterstützung meldet nichts. Daher läuft der Start in einen Timeout, und das Journal protokolliert das Ergebnis als Protokollfehler.

Wählen Sie den Typ anhand des tatsächlichen Programmverhaltens. Unterschiede zwischen simple, forking, oneshot und notify ist die entscheidende Auswahl für diese gesamte Fehlerklasse.

Wenn sich ein Dienst immer wieder beendet, beendet systemd die weiteren Startversuche und meldet, dass die Startanforderung zu häufig wiederholt wurde. Die Unit bleibt dann im Status failed, und systemd startet sie nicht automatisch neu. Sie können den Dienst manuell starten, sobald das Rate-Limit-Intervall abgelaufen ist. Alternativ können Sie sudo systemctl reset-failed myapp.service ausführen. Dadurch werden der Status failed und der Neustartzähler zurückgesetzt, sodass ein manueller Start sofort funktioniert. Das Erhöhen des Limits kaschiert nur das Symptom. Lesen Sie das Journal ab dem ersten Fehler und nicht ab dem letzten. Prüfen Sie außerdem was Restart=on-failure tatsächlich erneut startet, bevor Sie die Einstellung ändern.

Warum ist die Unit ohne Fehlermeldung inaktiv?

Eine Unit kann übersprungen werden, statt gestartet zu werden. Condition*-Direktiven sind absichtlich still: Wenn die Prüfung fehlschlägt, markiert systemd den Job als erfolgreich und führt nichts aus. Eine Unit mit ConditionPathExists=/etc/myapp/config.yml wird niemals gestartet, solange diese Datei fehlt. Sie meldet dabei ebenfalls keinen Fehler.

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

ConditionResult=no bestätigt das Überspringen. Im Journal wird die Prüfung genannt, die nicht erfüllt war. Verwenden Sie stattdessen eine Assert*-Direktive, wenn ein fehlendes Vorabkriterium ausdrücklich einen Fehler auslösen soll. Bedingungen, Assertions und Unit-Reihenfolge erläutert, welche Prüfung an welche Stelle gehört.

Daneben gibt es weitere stille Fälle. Ein Fehler „konnte nicht gefunden werden“ bedeutet meist, dass sich die Datei im falschen Verzeichnis befindet oder dass Sie die Konfiguration noch nicht neu geladen haben: Selbst erstellte Unit-Dateien gehören nach /etc/systemd/system/. Eine maskierte Unit verweigert jeden Start, bis sudo systemctl unmask myapp.service dies aufhebt. Und systemctl enable schlägt bei einer Unit ohne [Install]-Abschnitt fehl. Fügen Sie ihr daher WantedBy=multi-user.target hinzu.

Was geschah, wenn der Prozess beendet und nicht wegen eines Fehlers beendet wurde?

code=killed unterscheidet sich von code=exited. Etwas hat den Prozess von außen beendet. status=9/KILL weist häufig auf den Out-of-Memory-Killer (OOM-Killer) hin. In diesem Fall nennt das Journal den ausgewählten Prozess. SIGKILL zeigt jedoch nicht, wer das Signal gesendet hat: systemd sendet es ebenfalls, wenn ein zu stoppender Dienst nach TimeoutStopSec= weiterhin SIGTERM ignoriert. Prüfen Sie daher, ob gerade ein Stop oder Neustart ausgeführt wurde, bevor Sie den Arbeitsspeicher als Ursache annehmen. Eine selbst gesetzte Begrenzung bewirkt dasselbe innerhalb der Cgroup (Control Group). Prüfen Sie deshalb den freien Arbeitsspeicher auf dem Host mit free -m und suchen Sie in der Unit nach einem MemoryMax=. MemoryMax, CPUQuota und die anderen Cgroup-Begrenzungen erklärt, welche Begrenzung einen Prozess beendet und welche ihn nur verlangsamt.

status=15/TERM direkt nach einem Startversuch bedeutet normalerweise, dass systemd den Start wegen einer Zeitüberschreitung beendet hat und den Prozess terminierte. Damit gelangen Sie zurück zu Type=.

Zwei Gewohnheiten verhindern die meisten dieser Fehler

Verwenden Sie überall absolute Pfade. systemd startet nicht Ihre Login-Shell. Daher gibt es weder .bashrc noch .profile und auch keine aktivierte virtuelle Umgebung. $PATH für einen Systemdienst ist eine kurze, fest eingebaute Liste. Sie enthält weder /opt noch die Shims eines Sprachversionsmanagers. Schreiben Sie /usr/bin/python3 oder /opt/myapp/venv/bin/python vollständig aus. command -v myapp gibt in Ihrer Shell den Pfad aus, den Sie kopieren können. Dieselbe Regel gilt für WorkingDirectory=, EnvironmentFile= und jeden Pfad in ReadWritePaths=.

ExecStart= ist keine Shell. systemd teilt die Zeile in Wörter auf und ruft execve() selbst auf. Pipes, Umleitungen, Globs, &&, Backticks und ~ haben keine Bedeutung. Sie erreichen Ihr Programm als literale Argumente. ExecStart=/usr/bin/myapp --flag > /tmp/out.log übergibt > und /tmp/out.log an myapp. Dieses beendet sich dann mit einem Verwendungsfehler, der nicht wie ein systemd-Problem aussieht. Wenn Sie Shell-Funktionen benötigen, müssen Sie eine Shell aufrufen.

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

Für die reine Ausgabe benötigen Sie das nicht. Die Ausgabe eines Dienstes wird standardmäßig in das Journal geschrieben. StandardOutput=append:/var/log/myapp.log schreibt in eine Datei, ohne dass eine Shell beteiligt ist.

Die Variablenexpansion ist entsprechend eingeschränkt. $MYVAR und ${MYVAR} werden aus Environment= und EnvironmentFile= ersetzt. Auch die wenigen Variablen, die systemd selbst setzt, werden berücksichtigt, beispielsweise $USER. %-Spezifizierer wie %i werden ebenfalls expandiert. Nichts aus Ihrer Login-Shell wird expandiert. $HOME wird nur gesetzt, wenn die Unit über User= verfügt, und zwar über den Standardwert SetLoginEnvironment=. Ein Dienst, der als root ohne User= läuft, hat daher kein $HOME, sofern Sie es nicht setzen. Ein EnvironmentFile= ist ebenfalls kein Shell-Skript. export gehört nicht hinein, seine Anführungsregeln unterscheiden sich von bash, und eine fehlende Datei führt zu einem fatalen Fehler, sofern Sie dem Pfad nicht - voranstellen.

Arbeiten Sie die Schritte auf einem Live-Server ab

Lesen Sie den Code, weisen Sie die Ursache nach, ändern Sie genau eine Sache und starten Sie den Dienst neu. Diese Reihenfolge ist wichtiger, als jede Zahl zu kennen. Sie verhindert, dass Sie drei spekulative Änderungen gleichzeitig vornehmen und anschließend nicht mehr wissen, welche davon geholfen hat. Derselbe Ablauf funktioniert auch für Units, die Sie nicht selbst geschrieben haben. Ein Timer, der nie ausgelöst wird, gehört zu einem Dienst, der nie gestartet wurde. Debuggen Sie deshalb zuerst den Dienst: ein systemd-Timer und der von ihm ausgelöste Dienst schlagen aus genau den oben beschriebenen Gründen fehl. Der Timer verbirgt die Ausgabe, bis Sie sie im Journal abfragen. Ein typisches Beispiel unter Arch Linux ist reflector.timer: Schlägt reflector.service fehl, bleibt /etc/pacman.d/mirrorlist unbemerkt auf dem alten Stand, und pacman lädt weiter von langsamen Mirrors, bis Sie mirrorlist und Reflector richtig einrichten.

FAQ

Was bedeutet status=203/EXEC in systemctl status?

systemd hat alle von der Unit angeforderten Einstellungen vorgenommen, aber der execve()-Aufruf ist fehlgeschlagen. Ihr Programm wurde daher nie gestartet. Prüfen Sie diese vier Punkte in dieser Reihenfolge: Der in ExecStart= angegebene Pfad ist vorhanden und absolut, die Datei hat das Ausführungsbit, der Shebang nennt einen Interpreter, der im PATH des Dienstes vorhanden ist, und die Datei verwendet Unix-Zeilenenden. file meldet beim letzten Punkt "with CRLF line terminators". Dadurch wird der Interpretername zu /bin/bash\r, und der Kernel verweigert die Ausführung.

Warum startet mein Dienst und beendet sich dann sofort?

Die Unit-Datei beschreibt ein Verhalten, das das Programm nicht aufweist. Bei Type=simple erwartet systemd, dass das Programm im Vordergrund bleibt. Ein Daemon, der in den Hintergrund forkt, wirkt daher in dem Moment beendet, in dem er forkt. Bei Type=forking wartet systemd, bis der erste Prozess beendet wird. Ein Vordergrundprogramm lässt den Startauftrag daher hängen, bis TimeoutStartSec= abläuft. Stimmen Sie Type= auf das Programm ab. Wenn das Programm einen Vordergrundschalter anbietet, verwenden Sie diesen Schalter zusammen mit dem Standardwert Type=simple.

Wie sehe ich den tatsächlichen Fehler statt der kurzen Statusausgabe?

systemctl status gibt nur die letzten Journalzeilen aus und kürzt lange Zeilen. Führen Sie journalctl -u myapp.service -b --no-pager aus, um alles anzuzeigen, was die Unit während dieses Boots protokolliert hat. Ergänzen Sie -n 200, um die Ausgabe auf die letzten 200 Zeilen zu beschränken, oder leiten Sie sie an grep weiter. Wenn die Anwendung eine eigene Logdatei schreibt, lesen Sie auch diese. systemd erfasst nur, was das Programm an die Standardausgabe und den Standardfehler sendet.

Warum ist meine Unit ohne Fehlermeldung inaktiv?

In den meisten Fällen hat eine Condition*-Direktive den Start übersprungen. Diese Prüfungen erfolgen ohne Meldung: Eine nicht erfüllte Bedingung markiert den Startauftrag als erfolgreich. Führen Sie systemctl show myapp.service -p ConditionResult aus und suchen Sie nach ConditionResult=no. Lesen Sie anschließend die Journalzeile, in der die Prüfung genannt wird. Die andere häufige Ursache ist eine maskierte Unit. Sie verweigert jeden Start, bis sudo systemctl unmask die Maskierung aufhebt.

Benötige ich nach jeder Änderung an einer Unit-Datei daemon-reload?

Ja, bei jeder Änderung an einer Unit-Datei oder einem Drop-in. sudo systemctl daemon-reload veranlasst systemd, die Dateien erneut von der Festplatte einzulesen. Anschließend wendet sudo systemctl restart myapp.service die Änderungen auf den laufenden Dienst an. Nach systemctl edit ist dies nicht erforderlich, da dieser Befehl automatisch neu lädt. Ebenso ist dies nach der Änderung einer Konfigurationsdatei der Anwendung nicht erforderlich, sofern diese Datei nicht zu systemd gehört.

War dieser Artikel hilfreich?

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