Spanner-Fehlercodes

Auf dieser Seite werden Spanner-Fehlercodes und empfohlene Maßnahmen zur Behandlung dieser Fehler beschrieben. Google APIs, einschließlich Spanner, verwenden die von google.rpc.Code definierten kanonischen Fehlercodes.

Wenn eine Spanner-Anfrage erfolgreich ist, gibt die API einen HTTP-Statuscode 200 OK zusammen mit den angeforderten Daten im Text der Antwort zurück.

Wenn eine Anfrage fehlschlägt, gibt die Spanner API einen HTTP-Statuscode 4xx oder 5xx zurück, der den Fehler allgemein identifiziert, sowie eine Antwort, die Informationen zu den Fehlerursachen enthält.

Das Antwortobjekt enthält ein einzelnes Feld error, dessen Wert die folgenden Elemente umfasst:

Element Beschreibung
code Ein HTTP-Statuscode, der den Anfragefehler allgemein identifiziert.
message Spezifische Informationen zum Anfragefehler.
status Die kanonischen Fehlercode (google.rpc.Code) für Google APIs. Die Codes, die von der Spanner API zurückgegeben werden können, werden unter Fehlercodes aufgeführt.

Wenn eine Anfrage mit dem Inhaltstyp application/x-protobuf zu einem Fehler führt, wird als Nutzlast die serialisierte Meldung google.rpc.Status zurückgegeben.

Fehlercodes

Es wird empfohlen, Fehler durch Prüfung des Werts des kanonischen Fehlercodes (google.rpc.Code) zu klassifizieren. Bei JSON-Fehlern wird dieser Code im Feld status angezeigt. Bei Fehlern vom Typ application/x-protobuf wird er im Feld code angezeigt.

Fehlercode Beschreibung Empfohlene Maßnahmen
ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Parallelitätsproblems wie einer fehlgeschlagenen Sequencer-Überprüfung oder einem Transaktionsabbruch. Gibt an, dass ein Konflikt mit einer anderen Anfrage bestand. Bei einem nicht transaktionalen Commit:
Wiederholen Sie die Anfrage oder strukturieren Sie Ihre Entitäten, um Konflikte zu reduzieren.

Bei Anfragen, die Teil eines transaktionalen Commits sind:
Wiederholen Sie die gesamte Transaktion oder strukturieren Sie Ihre Entitäten, um Konflikte zu reduzieren.
ALREADY_EXISTS Die Entität, die ein Client erstellen wollte, ist bereits vorhanden (z. B. beim Einfügen einer Zeile mit einem vorhandenen Primärschlüssel). Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
CANCELLED Der Vorgang wurde abgebrochen, üblicherweise vom Aufrufer. Wiederholen Sie den Vorgang.
DEADLINE_EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Prüfen Sie, ob die Frist ausreichend ist. Verwenden Sie eine Frist, die dem tatsächlichen Zeitpunkt entspricht, zu dem eine Antwort nützlich ist. Bei Vorgängen, die den Systemstatus verändern, kann ein Fehler zurückgegeben werden, auch wenn der Vorgang erfolgreich abgeschlossen wurde.

Tipps finden Sie unter Fehlerbehebung bei Fehlern aufgrund überschrittener Fristen.
FAILED_PRECONDITION Der Vorgang wurde abgelehnt, weil eine Vorbedingung für die Anfrage nicht erfüllt wurde. Das Nachrichtenfeld der Fehlerantwort enthält Informationen zu der nicht erfüllten Vorbedingung. Beispiel: Lesen oder Abfragen eines Zeitstempels, der die maximale Zeitstempelveralterung überschritten hat. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
INTERNAL Der Server hat einen Fehler zurückgegeben. Einige Invarianten, die vom zugrunde liegenden System erwartet werden, sind fehlerhaft. Versuchen Sie es erst dann noch einmal, wenn Sie die genauen Umstände und die Ursache des Fehlers kennen.
INVALID_ARGUMENT Der Client hat einen ungültigen Wert angegeben. Im Nachrichtenfeld der Fehlerantwort ist angegeben, welcher Wert ungültig war. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
NOT_FOUND Gibt an, dass eine angeforderte Entität, z. B. eine Entität, die aktualisiert werden soll, oder eine Tabelle oder Spalte, die abgefragt werden soll, nicht vorhanden ist. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
OUT_OF_RANGE Beim Vorgang wurde versucht, den gültigen Bereich zu überschreiten. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
PERMISSION_DENIED Der Nutzer war zu dieser Anfrage nicht berechtigt. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
RESOURCE_EXHAUSTED Eine Ressource ist erschöpft.

Auf der Administratorebene kann es sein, dass das Projekt sein Kontingent überschritten hat oder der Speicherplatz für das gesamte Dateisystem ausgegangen ist.

Auf der Datenebene kann dies passieren, wenn Ihre Spanner-Knoten überlastet sind.

Weitere Informationen finden Sie auch unter Sitzungsbezogene Fehlercodes.		 Prüfen Sie für die Administratorebene, ob Sie Ihr Spanner- oder Projektkontingent überschritten haben. Wenn Sie ein Kontingent überschritten haben, beantragen Sie eine Kontingenterhöhung oder warten Sie, bis das Kontingent zurückgesetzt wird, bevor Sie es noch einmal versuchen. Konfigurieren Sie Ihre Wiederholungsversuche so, dass ein exponentieller Backoff verwendet wird.

Prüfen Sie für die Datenebene, ob die Kapazität Ihrer Spanner-Knoten überschritten wurde. Spanner wiederholt diese Fehler in der Clientbibliothek. Wenn alle Wiederholungsversuche fehlschlagen, lesen Sie den Abschnitt Fehler bei der Ablaufsteuerung.

Wenn in Ihrer Anwendung RESOURCE_EXHAUSTED-Fehler auftreten, behandeln Sie die Situation im Allgemeinen wie einen UNAVAILABLE-Fehler und wiederholen Sie den Vorgang mit exponentiellem Backoff.
UNAUTHENTICATED Die Anfrage enthält keine gültigen Authentifizierungsdaten für diesen Vorgang. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
UNAVAILABLE Der Server ist nicht verfügbar. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Es ist nicht immer sicher, nicht idempotente Vorgänge zu wiederholen.
UNIMPLEMENTED Dieser Vorgang ist nicht implementiert oder wird bei diesem Dienst nicht unterstützt bzw. ist bei diesem Dienst nicht aktiviert. Wiederholen Sie den Vorgang erst, wenn das Problem behoben ist.
UNKNOWN Der Server hat einen unbekannten Fehler zurückgegeben. Fehler, die von APIs ausgelöst werden, die nicht genügend Fehlerinformationen liefern, können in diesen Fehler umgewandelt werden. Prüfen Sie, ob Ihre Anfrage sicher ist. Wiederholen Sie den Vorgang dann mit exponentiellem Backoff.

Sitzungsfehler

Spanner verwendet Sitzungen, um die Interaktionen zwischen Ihrer Anwendung und der Datenbank zu verwalten. Sitzungen stellen eine Verbindung zur Datenbank dar und ermöglichen Vorgänge wie Lese- und Schreibvorgänge.

Häufige sitzungsbezogene Fehler, die in Ihrer Anwendung auftreten können, sind:

Sitzung nicht gefunden

Der Fehler Session not found tritt auf, wenn Ihre Anwendung versucht, eine Sitzung zu verwenden, die nicht mehr vorhanden ist. Dafür kann es verschiedene Gründe geben.

  • Ihre Clientanwendung löscht möglicherweise explizit eine Sitzung. Wenn Sie beispielsweise einen Datenbankclient in Ihrem Code schließen oder die deleteSessions API direkt aufrufen, wird die Sitzung entfernt. Wenn Sie keine der Spanner-Clientbibliotheken verwenden, erstellen Sie eine neue Sitzung, wenn dieser Fehler auftritt. Fügen Sie die neue Sitzung Ihrem Sitzungspool hinzu und entfernen Sie die gelöschte Sitzung aus dem Pool.

  • Spanner löscht Sitzungen unter bestimmten Bedingungen auch automatisch.

    • Eine Sitzung wird gelöscht, wenn sie länger als eine Stunde inaktiv ist. Dies kann bei Datenstreamjobs auftreten, bei denen die nachgelagerte Verarbeitung länger dauert als das Zeitlimit für die Inaktivität der Sitzung. Wenn Sie einen Dataflow-Job verwenden, fügen Sie nach dem Spanner-Lesevorgang in der Dataflow-Pipeline einen Reshuffle-Transformationsvorgang ein. So kann der Spanner-Lesevorgang von den nachfolgenden Verarbeitungsschritten mit langer Ausführungszeit entkoppelt werden.

    • Spanner löscht eine Sitzung auch, wenn sie älter als 28 Tage ist. Wenn Sie die Clientbibliothek verwenden, werden diese Fälle automatisch behandelt. Wenn Sie keine der Spanner-Clientbibliotheken verwenden, erstellen Sie eine neue Sitzung, wenn dieser Fehler auftritt. Fügen Sie die neue Sitzung Ihrem Sitzungspool hinzu und entfernen Sie die gelöschte Sitzung aus dem Pool.

  • Wenn Sie eine der Spanner-Clientbibliotheken verwenden, werden Sitzungen automatisch von der Bibliothek verwaltet. Wenn dieser Fehler auftritt, prüfen Sie, ob in Ihrem Code Sitzungen explizit gelöscht werden, z. B. durch Schließen des Datenbankclients. Gelegentlich kann dies auch durch ein Problem in der Sitzungsverwaltung der Clientbibliothek verursacht werden.

Ressource erschöpft

Die Fehler RESOURCE_EXHAUSTED: No session available in the pool oder RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session weisen darauf hin, dass Ihre Anwendung keine Sitzung aus dem Sitzungspool abrufen kann. Das passiert, wenn keine Sitzungen verfügbar sind, um neue Lese- oder Schreibanfragen zu verarbeiten.

In der folgenden Tabelle werden einige Gründe für diese Fehler und die entsprechenden empfohlenen Maßnahmen beschrieben.

Grund Empfohlene Maßnahmen
Alle Sitzungen im Pool werden verwendet. Ihre Anwendung erhält möglicherweise mehr gleichzeitige Anfragen als die konfigurierte maximale Anzahl von Sitzungen. Alle Sitzungen im Pool sind belegt und es sind keine Sitzungen für neue Anfragen verfügbar. Multiplex-Sitzungen aktivieren Bei gemultiplexten Sitzungen können mehrere Transaktionen und Lesevorgänge eine einzelne Sitzung gemeinsam nutzen. Dadurch kann die Gesamtzahl der von Ihrer Anwendung benötigten Sitzungen reduziert werden. Sie können die Konfiguration maxSession oder minSession auch in den Einstellungen für den Sitzungspool erhöhen.
Die Bearbeitung von Anfragen dauert lange. Lange Lese- oder Schreibanfragen können alle verfügbaren Sitzungen über einen längeren Zeitraum belegen. Wenn diese Anfragen länger dauern als das Zeitlimit für den Sitzungserwerb, können neue Anfragen keine Sitzung aus dem Sitzungspool erhalten. Untersuchen Sie, warum die Bearbeitung Ihrer Anfragen so lange dauert. Optimieren Sie Ihre Abfragen oder Anwendungslogik, um die Ausführungszeit zu verkürzen. Sie können das Zeitlimit für den Abruf von Sitzungen erhöhen. Sie können auch gemultiplexte Sitzungen für infrage kommende Clientbibliotheken aktivieren, um die Sitzungsauslastung zu verbessern.
Es gibt Sitzungslecks. Ein Sitzungsleck tritt auf, wenn Ihre Anwendung eine Sitzung aus dem Pool auscheckt, sie aber nach Abschluss der Anfrage nicht zurückgibt. Das passiert in der Regel, wenn Iteratoren oder Ergebnismengen in Ihrem Code nicht richtig geschlossen werden. Wenn alle Sitzungen abgelaufen sind, sind keine Sitzungen für neue Anfragen verfügbar. Debuggen Sie Ihren Anwendungscode, um die Sitzungslecks zu identifizieren und zu beheben. Achten Sie darauf, dass in Ihrem Code alle Iteratoren und Ergebnismengen ordnungsgemäß geschlossen werden. Weitere Informationen finden Sie unter Lösungen zur Erkennung von Sitzungslecks. Sie können auch die Funktion automatische Bereinigung von Sitzungslecks verwenden, um festzulegen, dass inaktive Transaktionen in Ihrem Sitzungspool automatisch aufgelöst werden.
Das Erstellen von Sitzungen dauert lange. Das Erstellen einer Sitzung ist ein rechenintensiver Vorgang. Clientbibliotheken senden BatchCreateSessions-APIs, um erste Sitzungen zu erstellen (basierend auf der minSession-Konfiguration), und CreateSessions-APIs für zusätzliche Sitzungen (bis zum maxSession). Wenn das Erstellen von Sitzungen länger als das Zeitlimit für das Abrufen von Sitzungen dauert, kann es bei neuen Anfragen zu Zeitüberschreitungen kommen, während auf Sitzungen gewartet wird. Prüfen Sie die Latenz von BatchCreateSessions- und CreateSessions-API-Aufrufen. Eine langsame Sitzungserstellung kann auf Ressourcenprobleme auf Spanner-Seite oder eine große Anzahl gleichzeitiger Sitzungserstellungsvorgänge zurückzuführen sein.

Fehler bei Mechanismen zur Ablaufsteuerung

Spanner kann seinen Ablaufsteuerungsmechanismus aktivieren, um sich unter den folgenden Bedingungen vor Überlastung zu schützen:

  • Die CPU-Auslastung auf dem Spanner-Knoten ist hoch. Wenn Sie vermuten, dass Ihre Anfrage eine hohe CPU-Auslastung verursacht, können Sie das Problem mit den Messwerten zur CPU-Auslastung untersuchen.
  • Es kann Hotspots geben, die die Bearbeitungszeit der Anfrage verlängern. Wenn Sie vermuten, dass Ihre Anfrage Hotspots verursacht, lesen Sie den Hilfeartikel Hotspots in der Datenbank finden. Weitere Informationen finden Sie unter Key Visualizer.

Der Mechanismus zur Ablaufsteuerung wird von den folgenden Clientbibliotheken unterstützt:

Die Gesamtzeit für die Ausführung der Anfrage verlängert sich durch die Verwendung des Flusskontrollmechanismus nicht. Ohne diesen Mechanismus wartet Spanner, bevor die Anfrage verarbeitet wird, und gibt schließlich einen DEADLINE_EXCEEDED-Fehler zurück.

Wenn der Ablaufsteuerungsmechanismus aktiv ist, werden Anfragen von Spanner an den Client zurückgegeben, damit er sie noch einmal versucht. Wenn der Wiederholungsversuch die gesamte vom Nutzer angegebene Frist in Anspruch nimmt, erhält der Client einen RESOURCE_EXHAUSTED-Fehler. Dieser Fehler wird zurückgegeben, wenn Spanner schätzt, dass die Verarbeitung der Anfrage zu lange dauert. Der Fehler wird an die Flusssteuerung weitergegeben und Spanner wiederholt die Anfrage an den Client, anstatt Wiederholungen intern anzusammeln. So kann Spanner zusätzlichen Ressourcenverbrauch vermeiden.