Netzwerk

curl-Exit-Code-Referenz

Vollständige Referenz der curl-Exit-Codes mit Bedeutung, häufigen Ursachen und Lösungen für Entwickler, die CI/CD-Pipelines und Shell-Skripte debuggen. Enthält ein Nachschlage-Tool — Codenummer eingeben und sofort die Details anzeigen.

Referenztabelle der curl-Exit-Codes
Code Konstantenname Bedeutung Häufige Ursachen
Verbindungs-/Initialisierungsfehler
1 CURLE_UNSUPPORTED_PROTOCOL Zeigt an, dass curl das in der URL angegebene Protokoll nicht unterstützt. Tritt auf, wenn eine curl-Binärdatei verwendet wird, in der dieses Protokoll (z. B. gopher, ldap) beim Build deaktiviert wurde, oder bei einem Tippfehler im URL-Schema.
2 CURLE_FAILED_INIT Zeigt an, dass die interne Initialisierung von curl fehlgeschlagen ist. Ein seltener Initialisierungsfehler auf niedriger Ebene, meist verursacht durch Speichermangel oder eine anomale Umgebung.
3 CURLE_URL_MALFORMAT Zeigt an, dass die angegebene URL fehlerhaft ist und von curl nicht interpretiert werden kann. Tritt auf, wenn der URL das Schema fehlt (z. B. http://) oder sie ungültige Zeichen enthält.
5 CURLE_COULDNT_RESOLVE_PROXY Zeigt an, dass curl den Hostnamen des angegebenen Proxy-Servers nicht auflösen konnte. Verursacht durch einen Tippfehler im mit --proxy angegebenen Hostnamen oder einen DNS-Fehler speziell des Proxys.
6 CURLE_COULDNT_RESOLVE_HOST Zeigt an, dass curl den Hostnamen des Zielservers nicht (per DNS) auflösen konnte. Meist verursacht durch einen Tippfehler im Domainnamen, einen Ausfall des DNS-Servers oder die Ausführung in einer Offline-Umgebung.
7 CURLE_COULDNT_CONNECT Zeigt an, dass der Hostname zwar aufgelöst wurde, curl aber keine TCP-Verbindung zum Server herstellen konnte. Tritt durch eine falsche Portnummer, eine Blockierung durch eine Firewall oder einen ausgefallenen Server auf.
8 CURLE_WEIRD_SERVER_REPLY Zeigt an, dass curl vom Server eine unerwartete Antwort erhielt, die nicht interpretiert werden konnte. Häufig, wenn ein FTP-Server eine nicht standardkonforme Antwort zurückgibt, oder wenn curl versehentlich mit einem Server verbunden wird, der ein anderes Protokoll spricht.
9 CURLE_REMOTE_ACCESS_DENIED Zeigt an, dass curl eine Verbindung zum Server herstellen konnte, der Zugriff jedoch verweigert wurde. Tritt bei unzureichenden Berechtigungen für ein FTP-Verzeichnis oder bei einer serverseitigen IP-Beschränkung auf.
Datenübertragungsfehler
18 CURLE_PARTIAL_FILE Zeigt an, dass die Übertragung vor Abschluss unterbrochen wurde und nur ein Teil der Datei empfangen werden konnte. Tritt durch eine kurze Netzwerkunterbrechung auf, oder wenn der Server die Verbindung schließt, bevor die angekündigte Content-Length erreicht wurde.
23 CURLE_WRITE_ERROR Zeigt an, dass das Schreiben von Daten auf die lokale Festplatte oder an das Callback-Ziel fehlgeschlagen ist. Tritt auf, wenn der Speicherplatz voll ist oder curl keine Schreibberechtigung für die Ausgabedatei hat.
26 CURLE_READ_ERROR Zeigt an, dass das Lesen der hochzuladenden lokalen Datei fehlgeschlagen ist. Tritt auf, wenn die mit -T/--upload-file angegebene Datei nicht existiert oder curl keine Leseberechtigung dafür hat.
52 CURLE_GOT_NOTHING Zeigt an, dass curl eine Verbindung zum Server herstellen konnte, aber überhaupt keine Antwort erhielt. Meist verursacht durch einen Absturz des Serverprozesses mitten in der Anfrage, oder eine Fehlkonfiguration, die eine leere Antwort zurückgibt.
55 CURLE_SEND_ERROR Zeigt an, dass das Senden von Daten über das Netzwerk fehlgeschlagen ist. Tritt auf, wenn die Gegenseite die Verbindung sofort nach dem Aufbau trennt, oder aufgrund eines Problems mit der lokalen Netzwerkschnittstelle.
56 CURLE_RECV_ERROR Zeigt an, dass der Empfang von Daten aus dem Netzwerk fehlgeschlagen ist. Häufig zu beobachten, wenn die Gegenseite die Verbindung während der Übertragung unerwartet zurücksetzt (Connection reset by peer).
63 CURLE_FILESIZE_EXCEEDED Zeigt an, dass die Dateigröße das mit --max-filesize festgelegte Limit überschritten hat. Tritt auf, wenn die Antwort größer ausfällt als erwartet und das aus Sicherheitsgründen konfigurierte Limit erreicht.
78 CURLE_REMOTE_FILE_NOT_FOUND Zeigt an, dass die angegebene Datei auf dem entfernten Server nicht existiert (z. B. bei FTP). Tritt durch einen Tippfehler im FTP-Pfad auf, oder wenn die Zieldatei bereits gelöscht oder verschoben wurde.
SSL/TLS-Zertifikatsfehler
35 CURLE_SSL_CONNECT_ERROR Zeigt an, dass während des SSL/TLS-Handshakes ein Problem aufgetreten ist, sodass die Verbindung nicht hergestellt werden konnte. Häufig verursacht durch eine Diskrepanz zwischen den vom Server und vom Client unterstützten TLS-Versionen oder Cipher-Suites.
51 CURLE_PEER_FAILED_VERIFICATION Zeigt an, dass die Überprüfung des Serverzertifikats fehlgeschlagen ist (z. B. stimmt der Zertifikatsinhalt nicht mit dem Hostnamen überein). Tritt beim Zugriff auf ein selbstsigniertes Zertifikat auf, oder wenn der Common Name/SAN des Zertifikats vom Zielhostnamen abweicht.
58 CURLE_SSL_CERTPROBLEM Zeigt ein Problem mit dem lokal angegebenen Client-Zertifikat an. Meist verursacht durch ein ungültiges Format der mit --cert angegebenen Zertifikatsdatei oder eine falsch eingegebene Passphrase.
60 CURLE_SSL_CACERT Zeigt an, dass die CA-Zertifikatskette zur Überprüfung des Serverzertifikats nicht bestätigt werden konnte. Tritt auf, wenn das CA-Zertifikatspaket veraltet ist, oder eine selbstsignierte CA (etwa eines internen Proxys) nicht im Trust Store registriert ist. -k/--insecure ist ein Workaround, wird für den Produktionseinsatz jedoch nicht empfohlen.
HTTP-/Authentifizierungsfehler
22 CURLE_HTTP_RETURNED_ERROR Zeigt an, dass bei angegebener Option -f/--fail die HTTP-Antwort einen Fehlerstatus von 400 oder höher zurückgegeben hat. Wird absichtlich in CI/CD-Skripten ausgelöst, die curl -f verwenden, um einen API-Fehlerstatus als Fehlschlag zu erkennen.
67 CURLE_LOGIN_DENIED Zeigt an, dass der Login (die Authentifizierung) beim Server abgelehnt wurde. Meist verursacht durch einen falschen Benutzernamen oder ein falsches Passwort, oder eine Kontosperrung bei Protokollen wie FTP/SMTP.
Sonstige
27 CURLE_OUT_OF_MEMORY Zeigt an, dass die Speicherzuweisung während der Ausführung von curl fehlgeschlagen ist. Eine seltene Situation, etwa der Versuch, eine sehr große Datei auf einem speicherbegrenzten System zu verarbeiten.
28 CURLE_OPERATION_TIMEDOUT Zeigt an, dass der Vorgang nicht innerhalb der mit --connect-timeout/--max-time usw. festgelegten Zeitgrenze abgeschlossen wurde. Einer der häufigsten Fehler in CI, verursacht durch eine langsame Serverantwort, Netzwerklatenz oder einen zu kurz eingestellten Timeout-Wert.
47 CURLE_TOO_MANY_REDIRECTS Zeigt an, dass die Anzahl der Weiterleitungen das mit --max-redirs festgelegte Limit überschritten hat. Tritt bei einer Weiterleitungsschleife (301/302, die sich zirkulär weiterleiten) oder einer legitimen Weiterleitungskette auf, die länger ist als das Standardlimit (50).

Tipps

  • Den Exit Code können Sie direkt danach mit $? (Bash) oder %errorlevel% (Windows) prüfen. In Shell-Skripten ist eine Verzweigung wie curl ... || echo "failed with $?" ein praktisches Muster.
  • 28 (Timeout) und 7 (Verbindungsfehler) werden oft verwechselt: 28 tritt auf, wenn die Antwort nach dem Verbindungsaufbau langsam kommt, während 7 auftritt, wenn die TCP-Verbindung selbst gar nicht erst zustande kommt.
  • Wenn 60 (CA-Zertifikatsfehler) auftritt, sollten Sie es nicht einfach mit -k/--insecure umgehen — prüfen Sie zunächst, ob Ihr CA-Zertifikatspaket (ca-certificates) aktuell ist. Der routinemäßige Einsatz von -k in Produktionsumgebungen erhöht das Risiko von Man-in-the-Middle-Angriffen.
  • 22 (HTTP-Fehler) tritt nur auf, wenn Sie die Option -f/--fail hinzufügen. Ohne diese liefert curl auch bei einer 404- oder 500-Antwort den Exit Code 0 (Erfolg) zurück — fügen Sie -f daher immer hinzu, wenn CI Fehler erkennen soll.

FAQ

Direkt nach der Ausführung des curl-Befehls können Sie ihn mit echo $? in Bash/Zsh, echo %errorlevel% in der Windows-Eingabeaufforderung oder $LASTEXITCODE in PowerShell prüfen.

Überprüfen Sie zunächst die Einstellungen von --connect-timeout und --max-time und verlängern Sie diese bei Bedarf. Wenn der Server dauerhaft langsam antwortet, prüfen Sie auch die Serverlast und den Netzwerkpfad (Proxy, VPN usw.).

Nein, es handelt sich um unterschiedliche Dinge. HTTP-Statuscodes (z. B. 404 oder 500) sind Antworten auf Protokollebene, die vom Server zurückgegeben werden, während curl-Exit-Codes das Ergebnis der Ausführung des curl-Befehls selbst anzeigen (Verbindungsfehler, Timeout usw.). Da curl HTTP-Fehler standardmäßig als Exit Code 0 (Erfolg) behandelt, sollten Sie beide nicht verwechseln.

Fügen Sie die Option curl -f (--fail) hinzu, damit curl den Exit Code 22 zurückgibt, sobald die HTTP-Antwort 400 oder höher ist. Ohne diese Option führt das erfolgreiche Abrufen einer Fehlerseite weiterhin zu Exit Code 0.

6 (COULDNT_RESOLVE_HOST) ist ein Fehler in der DNS-Phase, bei dem der Hostname nicht in eine IP-Adresse aufgelöst werden konnte. 7 (COULDNT_CONNECT) ist ein Fehler, bei dem die Namensauflösung erfolgreich war, aber die TCP-Verbindung zu dieser IP-Adresse nicht hergestellt werden konnte.
ツールくん

Übrigens – Das Exit-Code-System von curl

curl ist ein Kommandozeilen-Tool, dessen Entwicklung 1996 von Daniel Stenberg begonnen wurde, ursprünglich unter dem Namen „httpget“. Heute ist curl standardmäßig auf praktisch jeder Linux-Distribution, macOS sowie Windows 10 und neuer vorinstalliert und gehört damit zu den grundlegendsten Werkzeugen für Webentwickler.

Das Exit-Code-System entspricht direkt dem internen Fehler-Enum von libcurl, CURLcode, und ist als fortlaufende Nummerierung ab `CURLE_OK` (Erfolg, Exit Code 0) definiert. Lücken in der Nummerierung entstehen dadurch, dass im Laufe der Entwicklung einige Fehlercodes als veraltet markiert oder zusammengeführt wurden.

Interessanterweise bilden die Exit Codes von curl ein eigenständiges System, das unabhängig von der allgemeinen POSIX-Konvention (0 = Erfolg, 1 = allgemeiner Fehler) ist. Das bedeutet: Wer in einem Shell-Skript die Exit Codes mehrerer Tools gemeinsam verarbeiten möchte, muss die Bedeutung in jedem einzelnen Handbuch nachschlagen.

Weitere Tools in dieser Kategorie