Datei-Upload fehlgeschlagen: Ursache vor erneutem Versuch

Tim Koschützki

Mitgründer · Berlin, Deutschland · Bio anzeigen

Wenn ein Upload fehlschlägt, öffnen Sie im Browser den Bereich Netzwerk und reproduzieren Sie den Fehler einmal mit einer kleinen, gültigen Testdatei. Suchen Sie die Upload-Anfrage, untersuchen Sie ihre Antwort und gleichen Sie sie mit den Server-Logs ab, bevor Sie Limits ändern oder Retries hinzufügen. Diese Anleitung richtet sich an Entwickler, die Fehler in einem bestehenden Web-Dateiuploader untersuchen. Um die Ursache zu bestätigen, benötigen Sie Zugriff auf den Code zur Anfrageverarbeitung und die Logs.

Einen fehlgeschlagenen Versuch erfassen

Öffnen Sie die DevTools vor dem Hochladen. Aktivieren Sie Protokoll beibehalten, wenn das Absenden auf eine andere Seite führt. Untersuchen Sie dann URL, Methode, Status, Nutzlast, Antwort und Timing der Anfrage. Die Anleitung zum Bereich Netzwerk in Chrome⁠ zeigt, wo Sie diese Details finden. Prüfen Sie jede Anfrage im Upload-Ablauf: Das Abrufen einer Upload-URL, das Übertragen der Bytes und das Abschließen des Uploads können unabhängig voneinander fehlschlagen.

Notieren Sie Zeitpunkt, Dateigröße und Dateityp, Status sowie eine vom Dienst bereitgestellte Anfrage-ID. Mit dieser ID können Sie Proxy- und Anwendungs-Logs einander zuordnen. Ohne ID verwenden Sie Zeitstempel, Route und Testkonto. Nehmen Sie keine Cookies, Autorisierungsheader, signierten URLs oder Dateiinhalte in Berichte auf, die Sie teilen.

Vergleichen Sie die Datei, deren Upload fehlschlägt, mit einer kleinen Datei desselben unterstützten Formats. Schlagen beide Uploads fehl, erklärt die Größe allein den Fehler nicht. Schlägt nur der Upload der größeren Datei fehl, untersuchen Sie die Hinweise zu Größe und Zeitverlauf, bevor Sie ein Limit oder eine unterbrochene Anfrage als Ursache festlegen.

Die fehlerhafte Schicht lokalisieren

Betrachten Sie den Status als Anhaltspunkt. Die Antwort und die zugehörigen Logs zeigen, welche Komponente die Anfrage abgelehnt hat. Ein Proxy und eine Anwendung können denselben Status zurückgeben.

Dies sind Ansätze zur Untersuchung, keine allgemeingültige Zuordnung von Status zu Ursache. Beispielsweise bedeutet 413, dass der Anfrageinhalt zu groß ist, während 503 eine vorübergehende Nichtverfügbarkeit des Dienstes beschreibt. Dieser Status weist nicht auf einen vollen Datenträger hin. Siehe die Definitionen der HTTP-Statuscodes⁠.

HTTP-Fehler im Code sichtbar halten

fetch() wird bei HTTP-Fehlerantworten erfüllt⁠. Ein abgelehntes Promise und eine Antwort mit ok: false sind unterschiedliche Beobachtungen. Prüfen Sie response.ok, bevor Sie einen Body parsen: Eine HTML-Fehlerseite eines Proxys kann sonst zu einem irreführenden JSON-Parsing-Fehler führen.

Für einen bestehenden Multipart-Upload-Handler wahrt diese TypeScript-Hilfsfunktion den Unterschied. Sie nimmt die ausgewählte Datei und die URL Ihres Handlers entgegen und sendet ein Feld namens file. Verwenden Sie sie nur, wenn dies zu Ihrer API passt. Behalten Sie beim Anpassen der Anfrage die erforderliche Authentifizierung und CSRF-Behandlung Ihrer Anwendung bei. Der Handler muss bereits laufen.

async function uploadForDiagnosis(
  file: File | undefined,
  url: string,
): Promise<Response | undefined> {
  if (file === undefined) return

  const body = new FormData()
  body.append('file', file)
  const response = await fetch(url, { method: 'POST', body })
  if (!response.ok) {
    throw new Error(`Upload returned HTTP ${response.status}`)
  }
  return response
}

Übergeben Sie aus Ihrem bestehenden Submit-Handler das ausgewählte File und die Upload-URL, warten Sie auf das Ergebnis und behandeln Sie dort eine Ablehnung. Ohne Auswahl wird nichts gesendet; bei einer leeren Datei wird dennoch eine Anfrage gestellt. Upload returned HTTP 413 bedeutet, dass eine lesbare HTTP-Antwort eingegangen ist. Ein Netzwerk- oder CORS-Fehler im Browser führt zur Ablehnung von fetch() selbst und wird von dieser Hilfsfunktion weitergereicht. Die Hilfsfunktion plant keine Retries. Die zurückgegebene Antwort muss weiterhin die normale Erfolgsvalidierung Ihrer API durchlaufen. Eine Login-Weiterleitung, die mit 200 endet, belegt beispielsweise nicht, dass eine Datei angenommen wurde.

Setzen Sie Content-Type für diese Anfrage mit FormData nicht manuell. Der Browser liefert die Multipart-Boundary; das Überschreiben des Headers kann das Parsen verhindern⁠. Halten Sie mehrfaches Absenden deaktiviert, solange Ihr bestehender Upload-Handler noch arbeitet.

Die Komponente ändern, die den Upload abgelehnt hat

Ein Größenlimit entlang des Anfragewegs verfolgen

Angenommen, der Upload einer kleinen Datei gelingt und bei einer größeren wird 413 zurückgegeben. Wenn der Proxy die Ablehnung protokolliert und in der Anwendung keine passende Anfrage vorliegt, untersuchen Sie zuerst den Proxy. Vergewissern Sie sich, dass die Protokollierung von Anfragen in der Anwendung aktiviert ist, bevor Sie einen fehlenden Log-Eintrag als Beleg werten.

Bei NGINX begrenzt client_max_body_size⁠ den Anfrage-Body und lässt sich auf der Ebene http, server oder location setzen. Prüfen Sie die Konfiguration für die tatsächliche Upload-Route. Eine Multipart-Anfrage enthält neben der Datei auch Felder und Boundaries. Ein Limit für den Anfrage-Body muss daher Spielraum über die erlaubte Dateigröße hinaus bieten. Ein höheres Anwendungslimit hebt ein vorgelagertes Proxy-Limit nicht auf.

Wenn das dokumentierte Produktlimit die Datei zulassen sollte, passen Sie die ablehnende Schicht innerhalb Ihres Speicher- und Ressourcenbudgets an. Behalten Sie andernfalls das Limit bei und erläutern Sie es in der Benutzeroberfläche. Testen Sie erneut mit der ursprünglichen Datei, einer Datei knapp innerhalb der erlaubten Größe und einer darüber. Die letzte sollte weiterhin abgelehnt werden.

Den Ablehnungsgrund der Anwendung lesen

Wenn die Antwort auf eine fehlerhafte Anfrage oder eine nicht unterstützte Datei hinweist, vergleichen Sie die Anfrage mit der Schnittstellenspezifikation des Handlers. Erwartet er ein Multipart-Feld namens file, einen anderen Feldnamen oder einen rohen Body? Enthält die Anfrage die erforderlichen Metadaten? Ändern Sie weder das Anfrageformat noch die Dateiendung, bevor die Antwort oder das Log eine Abweichung erkennen lässt.

Wenn das tatsächliche Format der Datei nicht unterstützt wird, wählen Sie eine unterstützte Quelldatei oder konvertieren Sie sie mit einem geeigneten Tool. Eine Änderung von .exe in .jpg konvertiert den Inhalt nicht. Testen Sie erneut mit einer nachweislich gültigen Datei und behalten Sie eine unzulässige Datei als Negativtest bei.

CORS von einer gestörten Verbindung unterscheiden

Ein allgemeiner Fetch-Fehler im Browser benennt die Ursache nicht. Untersuchen Sie die konkrete Fehlermeldung in der Konsole zusammen mit dem Bereich Netzwerk und den Server-Logs.

• Wenn eine Preflight-Anfrage mit OPTIONS fehlschlägt, prüfen Sie den auf dem Server erlaubten Ursprung, die erlaubte Methode und die erlaubten Anfrageheader. Der Browser kann abbrechen, bevor er den Upload sendet.
• Wenn der Upload den Server erreicht, aber in dessen Antwort die erforderlichen CORS-Header fehlen, kann JavaScript diese Antwort nicht lesen. Der Server könnte die Datei bereits angenommen haben. Prüfen Sie den gespeicherten Zustand vor einem erneuten Versuch.
• Wenn der Browser einen Verbindungs- oder Zertifikatsfehler meldet, untersuchen Sie diese Verbindung. Wenn Ihr Code die Anfrage abgebrochen hat, finden Sie den Abbruch oder die Zeitüberschreitung, die ihn ausgelöst hat.

Konfigurieren Sie CORS auf dem antwortenden Server, auch für dessen Fehlerantworten. Ursprungsübergreifende Anfragen mit Zugangsdaten benötigen einen explizit erlaubten Ursprung und die passenden Einstellungen für Zugangsdaten; * ist kein Ersatz. Die CORS-Anleitung von MDN⁠ erläutert die Prüfungen von Preflight und Antwort. Testen Sie erneut vom ursprünglichen Browser-Ursprung aus und unter den ursprünglichen Authentifizierungsbedingungen. Eine erfolgreiche cURL-Anfrage belegt nicht, dass CORS im Browser funktioniert.

Verwenden Sie mode: 'no-cors' nicht als Lösung. Dadurch entsteht eine opake Antwort, deren Status und Body Ihr Code nicht untersuchen kann. Testen Sie sowohl einen angenommenen Upload als auch eine absichtliche Ablehnung erneut: Beide Antworten müssen für den erlaubten Ursprung lesbar bleiben.

Einen Serverfehler bis zum fehlgeschlagenen Vorgang verfolgen

Zu einer Antwort mit 5xx muss ein passender serverseitiger Fehler gefunden werden. Ermitteln Sie, ob der Fehler beim Parsen der Anfrage, beim Schreiben einer temporären Datei, beim Speichern des endgültigen Objekts oder bei der späteren Verarbeitung auftrat. Prüfen Sie bei Speicherung im Dateisystem den freien Speicherplatz, die Quote, den tatsächlichen Zielpfad und die Berechtigungen des Dienstkontos. Prüfen Sie auch den temporären Speicher. Ein beschreibbares Zielverzeichnis belegt nicht, dass der Upload-Parser Daten zwischenspeichern kann.

Wählen Sie die Korrektur anhand des zugrunde liegenden Fehlers. Beispielsweise unterscheiden die Node-Fehler EACCES und ENOENT⁠ zwischen einem Berechtigungsfehler und einem fehlenden Pfad. Korrigieren Sie den konkreten Pfad oder die Dienstberechtigung, wiederholen Sie dann denselben Upload und prüfen Sie die gespeicherten Bytes. Geben Sie das Upload-Verzeichnis nicht für alle zum Schreiben frei, um ein Berechtigungsproblem zu kaschieren. Wenn ein Gateway einen nicht verfügbaren Upstream meldet, prüfen Sie den Zustand der Anwendung, bevor Sie Datenträgereinstellungen oder Zeitlimits ändern.

Bei Unterbrechungen fortsetzbare Uploads ergänzen

Sobald gültige Uploads funktionieren, können wiederholte Verbindungsunterbrechungen den Einsatz fortsetzbarer Uploads rechtfertigen. Mit tus⁠ kann ein Client den gespeicherten Offset abfragen und mit einem kompatiblen Server ab dort fortfahren. Eine Datei nur im Browser in Blöcke aufzuteilen, schafft noch keine solche Abstimmung über Offsets, Speicherung und Abschluss.

Fortsetzbarkeit behebt weder eine ungültige Datei noch eine abgelehnte Anfrage, eine fehlerhafte CORS-Konfiguration oder erschöpften Speicherplatz. Wenn Sie sie einführen, testen Sie Unterbrechung und Wiederaufnahme und vergleichen Sie die fertig hochgeladene Datei mit dem Original. Wählen Sie mithilfe der tus-Implementierungen⁠ einen kompatiblen Client und Server aus.

Die Korrektur prüfen, ohne Schutzmaßnahmen zu entfernen

Führen Sie den ursprünglich fehlgeschlagenen Fall erneut aus, dann einen Upload mit einer gültigen kleinen Datei und einen mit einer bewusst unzulässigen Datei. Bestätigen Sie die erwartete HTTP-Antwort, das Annahmeergebnis der Anwendung und die gespeicherte Datei oder das endgültige Verarbeitungsergebnis. Vergleichen Sie bei einem unveränderten Upload die heruntergeladenen Bytes oder eine Prüfsumme mit dem Original. Ein abgeschlossener Fortschrittsbalken beschreibt nur die Übertragungsphase, die er misst.

Behalten Sie die serverseitige Größen- und Inhaltsvalidierung bei, auch wenn die Benutzeroberfläche vorab prüft. Behandeln Sie Dateinamen und angegebene MIME-Typen als nicht vertrauenswürdig, generieren Sie Namen für die Speicherung, beschränken Sie den Zugriff und setzen Sie Malware-Scans oder die Entfernung gefährlicher Inhalte ein, wenn Dateityp und Risiko dies erfordern. Die OWASP-Empfehlungen für Datei-Uploads⁠ beschreiben diese Schutzmaßnahmen. Eine hilfreiche Fehlermeldung erklärt dem Nutzer, was er ändern soll, und liefert dem Support eine Anfrage-ID. Interne Pfade, Stacktraces und Zugangsdaten bleiben dabei außerhalb der Antwort.