Fehlererklärungen

Wenn in Restow etwas fehlschlägt, endet das nicht in einem nackten Fehlertext. Die Meldung sagt drei Dinge, in Ihrer Sprache: was passiert ist, warum und was zu tun ist, mit einem Link auf die Seite, auf der Sie es erledigen können. Dieselbe Erklärung erscheint überall, wo ein Fehler auftaucht, und die Ursache dahinter ist ein stabiler Code, den Ihre eigenen Werkzeuge lesen können.

Wo Sie sie sehen

• Jobs. Ein fehlgeschlagener oder teilweise fehlgeschlagener Job, zum Beispiel ein Backup, ein Restore, ein Archiv-Sync oder eine Prüfung. Die Job-Seite erklärt den Fehler des Jobs selbst und darunter die fehlgeschlagenen Elemente, nach Ursache gruppiert.
• Fehlgeschlagene Elemente. Elemente, die ein Lauf nicht verarbeiten konnte, sind unter Fehlgeschlagene Elemente nach Ursache gruppiert. Elemente mit gleicher Ursache stehen einmal mit ihrer Anzahl da, und das jüngste Beispiel jeder Gruppe ist erklärt.
• Quellen. Eine Quelle mit gestörter Verbindung nennt den Grund, zum Beispiel dass die Administratorzustimmung fehlt.
• Verzeichnisabgleich. Ein fehlgeschlagener Verzeichnisabgleich einer Quelle.
• IMAP-Anmeldetest. Ein fehlgeschlagener Anmeldetest eines IMAP-Kontos.
• Prüfung. Eine rote oder gelbe Wiederherstellbarkeitsprüfung erklärt jeden Grund, den sie gefunden hat (siehe Backup und Restore).
• Server- und Client-Backups. Die Läufe eines Endpunkts erklären ihre Fehler auf dieselbe Weise (siehe Endpunkt-Backup).

So lesen Sie eine Erklärung

1. Die Überschrift nennt die Ursache in einem Satz, zum Beispiel „Der Restow-App fehlt eine Microsoft-365-Berechtigung“.
2. Was passiert ist. Was fehlgeschlagen ist, für welches Postfach, Laufwerk, welche Quelle oder welches Konto, und wann. Dazu der Schritt, in dem der Job stand, als er anhielt, und bei einem Lauf, wie viele Elemente betroffen waren.
3. Warum. Der Grund in einfachen Worten, mit den Fakten des Falls: die fehlende Berechtigung, der Host, der sich nicht erreichen lässt, die Sekunden, die Microsoft Restow warten lassen wollte.
4. Was zu tun ist. Nummerierte Schritte in der richtigen Reihenfolge. Ein Schritt, der auf eine andere Seite gehört, hat einen Link, der sie öffnet: Microsoft-365-Einstellungen öffnen, Quelle öffnen, Quellen öffnen, Geschützte Objekte öffnen, Speicher öffnen, Wiederherstellbarkeit öffnen oder Backup öffnen. Mehrere Schritte zur selben Seite verlinken sie einmal, beim ersten davon.
5. Jetzt erneut versuchen. Eine Schaltfläche, die nur dort erscheint, wo ein neuer Versuch helfen kann, sobald Sie die Ursache behoben haben. Sie fehlt bei Ursachen, bei denen ein neuer Versuch immer gleich scheitern würde, bis sich etwas ändert (ein Benutzer, den es nicht mehr gibt, ein zu großes Element), und solange Restow es schon selbst erneut versucht.
6. Anleitung zur Fehlersuche. Ein Link auf die Seite mit weiterer Hilfe (siehe unten).
7. Technische Details. Ein eingeklappter Bereich für eine Supportanfrage (siehe unten).

Restow versucht es automatisch erneut

Viele Ursachen sind vorübergehend: Drosselung, ein kurzer Ausfall, eine abgebrochene Verbindung. Ein Job, der so fehlgeschlagen ist, wird von selbst wieder eingereiht. Die Erklärung erscheint dann als Warnung, sagt Restow versucht es automatisch erneut und zeigt den fehlgeschlagenen Versuch („Versuch x von y ist fehlgeschlagen. Restow versucht es etwa … erneut.“) mit dem Zeitpunkt des nächsten Versuchs. Sie beschreibt den früheren Versuch, und Sie müssen nichts tun, solange die Wiederholungen nicht aufgebraucht sind. Die Spalte Vorübergehend in den Tabellen unten zeigt, welche Ursachen so behandelt werden.

Technische Details

Für eine Supportanfrage öffnen Sie Technische Details. Sie listen den Ursachencode, den Zeitpunkt und den Schritt auf, dazu, was der fehlgeschlagene Aufruf gemeldet hat, soweit es zutrifft:

• den HTTP-Status, den Graph-Fehlercode und den inneren Fehlercode, den Entra-Fehler (AADSTS) und die Korrelations-ID,
• die Request-ID, die Client-Request-ID und die Zeit laut Server (Serverzeit), nach denen der Microsoft-Support fragt,
• die Anfrage selbst (Methode und Pfad, ohne Query-String),
• bei IMAP: die Antwort des Servers, ihren Antwortcode, den Status und den Befehl,
• bei Netzwerk und System: den Host, den Port, den Systemaufruf, den Pfad, den SQL-Status der Datenbank.

Details für den Support kopieren legt die Liste in die Zwischenablage. Secrets werden entfernt, bevor etwas gespeichert wird: Passwörter, Schlüssel, Tokens, Authorization-Header, Zugangsdaten und Query-Strings in URLs sowie der Text einer fehlgeschlagenen Datenbankabfrage erscheinen nie in den Details.

Ältere Fehler

Ein Fehler, der vor 0.1.0 gespeichert wurde, zeigt statt einer Erklärung die Meldung, wie sie gespeichert wurde (Secrets entfernt), mit dem Hinweis, dass sie gespeichert wurde, bevor es strukturierte Ursachen gab. Ein Fehler, den Restow nicht einordnen kann, erhält die Ursache unknown, die die gespeicherte Meldung auf dieselbe Weise zeigt.

Der Link zur Fehlersuche

Der Link Anleitung zur Fehlersuche zeigt standardmäßig auf die Seite zur Fehlersuche dieser Dokumentation. Führen Sie ein eigenes Runbook, setzen Sie RESTOW_DOCS_TROUBLESHOOTING_URL in der .env auf dessen Adresse. Es ist eine Adresse für die ganze Installation: Jede Erklärung in der Oberfläche und das Feld docsUrl der Integrations-API zeigen dann dorthin. Ein fehlender abschließender Schrägstrich wird ergänzt.

In der Integrations-API und in Webhooks

Die Ursache ist Teil der Daten, die Ihre Integrationen schon lesen. Die Felder sind additiv: Eine Integration, die vor 0.1.0 geschrieben wurde, funktioniert weiter, und nichts wurde umbenannt oder entfernt. Siehe Integrations-API.

• Job-Objekte enthalten failure (die Ursache eines fehlgeschlagenen Jobs oder seines letzten Versuchs, oder null, wenn er nicht fehlgeschlagen ist oder aus der Zeit vor der Ursachenerfassung stammt, dann gibt es nur errorMessage) und bei einem beendeten Job itemCauses (die Codes hinter seinen fehlgeschlagenen Elementen mit Anzahl, die häufigsten zuerst, höchstens drei).
• Job-Details enthalten failures (jedes fehlgeschlagene Element mit seinem failure), failureCount und failureGroups (die fehlgeschlagenen Elemente nach Ursache gruppiert, die häufigsten zuerst).
• Gründe einer Prüfung enthalten failure, den erklärten Grund.
• Der letzte Backup-Job eines geschützten Objekts enthält ebenfalls failure.
• Der Webhook job.failed enthält die Ursache in data.job.failure: den code, ob sie transient ist, die params (zum Beispiel die Berechtigung oder den Host), die technical-Details, den Zeitpunkt, den Schritt und den Wiederholungsstand. Ein Ticket kann die Ursache nennen, ohne Text auszuwerten.

Ein failure-Objekt der API hat diese Felder: code (der stabile Ursachencode), category (microsoft, imap, network, storage, crypto, verify, config, endpoint oder system), transient, retryable, params, technical, occurredAt, step, retry (Versuch, Limit und nächster Versuch, wenn der Job wieder eingereiht ist), steps (was zu tun ist, als Schritt-IDs mit der Zielseite) und docsUrl. Die Texte schreibt der Client, in der Sprache der lesenden Person. Code, der code liest, sollte Werte akzeptieren, die er nicht kennt: Ein neueres Restow kann Ursachen hinzufügen.

Die Ursachencodes

Restow 0.1.0 ordnet Fehler 88 stabilen Ursachencodes zu. 21 davon gehören zu Server- und Client-Backups, die übrigen 67 betreffen Microsoft 365, IMAP, das Netzwerk, Speicherziele, Verschlüsselung, Prüfung, Konfiguration und die Plattform selbst. Die Tabellen führen jeden Code mit seiner Überschrift auf.

• Vorübergehend heißt, Warten kann genügen: Restow versucht den Job von selbst erneut, solange er Versuche übrig hat.
• Jetzt erneut versuchen sagt, ob die Schaltfläche erscheint, sobald Sie die Ursache behoben haben.

Microsoft 365 (graph.*)

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
graph.consent_missing	Die Administratorzustimmung für Microsoft 365 fehlt oder wurde zurückgezogen	Nein	Ja
graph.app_credentials_invalid	Microsoft akzeptiert die Zugangsdaten der Restow-App nicht	Nein	Ja
graph.tenant_not_found	Microsoft kennt diesen Mandanten nicht	Nein	Ja
graph.token_rejected	Microsoft hat das Zugriffstoken nicht akzeptiert	Ja	Ja
graph.permission_missing	Der Restow-App fehlt eine Microsoft-365-Berechtigung	Nein	Ja
graph.access_denied	Microsoft hat den Zugriff auf dieses Postfach oder Laufwerk verweigert	Nein	Ja
graph.mailbox_not_licensed	Dieser Benutzer hat kein nutzbares Exchange-Online-Postfach	Nein	Ja
graph.user_not_found	Der Benutzer oder das Postfach existiert nicht mehr	Nein	Nein
graph.onedrive_unavailable	Dieser Benutzer hat kein OneDrive, das Restow erreichen kann	Nein	Ja
graph.throttled	Microsoft bremst Restow aus (Drosselung)	Ja	Ja
graph.service_unavailable	Microsoft hatte ein vorübergehendes Dienstproblem	Ja	Ja
graph.item_not_found	Das Element wurde inzwischen bei Microsoft geändert oder gelöscht	Ja	Ja
graph.item_too_large	Das Element ist für Microsoft Graph zu groß	Nein	Nein
graph.item_unreadable	Das Element ist bei Microsoft beschädigt oder nicht lesbar	Nein	Nein
graph.delta_expired	Microsoft hat die Änderungsverfolgung eines Ordners ungültig gemacht	Ja	Ja
graph.quota_exceeded	Das Zielpostfach oder OneDrive ist voll	Nein	Ja
graph.request_rejected	Microsoft hat die Anfrage abgelehnt	Nein	Ja

IMAP (imap.*)

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
imap.auth_failed	Der IMAP-Server hat die Anmeldung abgelehnt	Nein	Ja
imap.oauth_failed	Die OAuth2-Anmeldung des IMAP-Kontos funktioniert nicht mehr	Nein	Ja
imap.credential_missing	Für dieses IMAP-Konto ist kein Passwort hinterlegt	Nein	Ja
imap.starttls_unavailable	Der Server bietet die eingestellte verschlüsselte Verbindung nicht an	Nein	Ja
imap.address_blocked	Verbindungen zu diesem IMAP-Host sind nicht erlaubt	Nein	Ja
imap.config_invalid	Die IMAP-Quelle ist nicht richtig eingerichtet	Nein	Ja
imap.command_failed	Der IMAP-Server hat einen Befehl abgelehnt	Nein	Ja
imap.mailbox_full	Das IMAP-Postfach ist voll	Nein	Ja
imap.connection_lost	Die Verbindung zum IMAP-Server wurde unterbrochen	Ja	Ja

Der Code imap.oauth_failed gehört zur OAuth2-Anmeldung von IMAP-Konten, die nicht Teil von 0.1.0 ist (IMAP-Quellen verwenden heute ein Passwort). Er ist der Vollständigkeit halber aufgeführt.

Netzwerk (network.*)

Diese gelten für jeden entfernten Host, auch Microsoft und IMAP-Server. Die Erklärung nennt den Host und sagt, ob es der IMAP-Server der Quelle oder ein Microsoft-Dienst ist.

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
network.dns	Der Hostname lässt sich nicht auflösen	Ja	Ja
network.unreachable	Der Host ist nicht erreichbar	Ja	Ja
network.timeout	Der Host hat nicht rechtzeitig geantwortet	Ja	Ja
network.tls	Das TLS-Zertifikat des Hosts wird nicht akzeptiert	Nein	Ja

Speicherziele (storage.*)

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
storage.path_missing	Der Speicherordner existiert nicht	Nein	Ja
storage.not_writable	Restow darf nicht in den Speicherordner schreiben	Nein	Ja
storage.full	Das Speicherziel ist voll	Nein	Ja
storage.access_denied	Der Speicherdienst hat den Zugriff verweigert	Nein	Ja
storage.credentials_invalid	Der Speicherdienst akzeptiert die Zugangsdaten nicht	Nein	Ja
storage.bucket_missing	Der Bucket existiert nicht	Nein	Ja
storage.wrong_region	Der Bucket liegt an einem anderen Endpunkt oder in einer anderen Region	Nein	Ja
storage.unreachable	Das Speicherziel ist nicht erreichbar	Ja	Ja
storage.timeout	Das Speicherziel hat nicht rechtzeitig geantwortet	Ja	Ja
storage.tls	Das TLS-Zertifikat des Speicher-Endpunkts wird nicht akzeptiert	Nein	Ja
storage.rate_limited	Der Speicherdienst begrenzt die Anfragen	Ja	Ja
storage.integrity	Daten im Speicher stimmen nicht mit dem überein, was Restow geschrieben hat	Nein	Ja
storage.error	Das Speicherziel hat einen unerwarteten Fehler gemeldet	Ja	Ja

Verschlüsselung (crypto.*)

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
crypto.key_missing	Der Verschlüsselungsschlüssel fehlt	Nein	Ja
crypto.key_invalid	Daten lassen sich mit dem Schlüssel von Restow nicht entschlüsseln	Nein	Ja

Prüfung und Wiederherstellbarkeit (verify.*)

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
verify.hash_mismatch	Wiederhergestellte Daten stimmen nicht mit dem Backup überein	Nein	Ja
verify.chunk_missing	Teile des Backups fehlen	Nein	Ja
verify.pack_unreadable	Backup-Daten lassen sich nicht aus dem Speicher lesen	Nein	Ja
verify.storage_corrupt	Die Speicherprüfung hat beschädigte Daten gefunden	Nein	Ja
verify.restore_test_failed	Die Test-Wiederherstellung ist fehlgeschlagen	Nein	Ja
verify.manifest_unreadable	Das Verzeichnis des letzten Backups lässt sich nicht lesen	Nein	Ja
verify.no_snapshot	Es gibt noch kein Backup zum Wiederherstellen	Nein	Nein
verify.snapshot_outdated	Das letzte Backup ist zu alt	Nein	Nein
verify.snapshot_stale	Das letzte Backup wird alt	Nein	Nein
verify.nothing_to_verify	Das Backup enthält nichts, was sich prüfen ließe	Nein	Nein
verify.restore_test_unconfirmed	Das Ziel hat die Test-Wiederherstellung nicht bestätigt	Nein	Ja

Konfiguration (config.*)

Dinge, die Sie in Ordnung bringen müssen, bevor ein Job laufen kann.

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
config.source_not_connected	Die Quelle ist noch nicht verbunden	Nein	Ja
config.source_disabled	Die Quelle ist ausgeschaltet	Nein	Ja
config.object_excluded	Dieses Objekt ist vom Schutz ausgenommen	Nein	Nein
config.object_orphaned	Dieses Objekt gibt es an der Quelle nicht mehr	Nein	Nein
config.app_not_configured	Die Microsoft-365-App dieser Installation ist nicht eingerichtet	Nein	Ja
config.invalid	Eine Einstellung verhindert, dass der Job läuft	Nein	Ja

Server und Clients (endpoint.*)

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
endpoint.no_paths	Keiner der eingestellten Ordner existiert auf dem Rechner	Nein	Ja
endpoint.pre_hook_failed	Der Befehl vor der Sicherung ist fehlgeschlagen	Nein	Ja
endpoint.post_hook_failed	Der Befehl nach der Sicherung ist fehlgeschlagen	Nein	Ja
endpoint.timeout	Der Lauf hat zu lange gedauert	Ja	Ja
endpoint.target_not_empty	Der Wiederherstellungsordner ist nicht leer	Nein	Ja
endpoint.invalid_task	Der Rechner konnte die Anforderung nicht ausführen	Nein	Ja
endpoint.hash_mismatch	Eine wiederhergestellte Datei passt nicht zur gespeicherten Prüfsumme	Nein	Ja
endpoint.file_missing	Eine Stichprobendatei fehlt in der Sicherung	Nein	Ja
endpoint.file_not_regular	Eine Stichprobendatei ist keine reguläre Datei	Nein	Nein
endpoint.read_error	Einige Dateien konnten nicht gelesen werden	Nein	Ja
endpoint.restic_failed	Das Sicherungsprogramm wurde mit einem Fehler beendet	Nein	Ja
endpoint.repository_locked	Das Repository ist belegt	Ja	Ja
endpoint.repository_missing	Das Repository wurde nicht gefunden	Nein	Ja
endpoint.repository_password	Das Repository-Passwort wird abgelehnt	Nein	Nein
endpoint.repository_refused	Der Server hat die Anfrage abgelehnt	Nein	Nein
endpoint.repository_damaged	Das Repository ist beschädigt	Nein	Ja
endpoint.network	Der Rechner konnte den Server nicht erreichen	Ja	Ja
endpoint.agent_stopped	Der Agent ist während des Laufs stehen geblieben	Ja	Ja
endpoint.interrupted	Der Lauf wurde unterbrochen	Ja	Nein
endpoint.silent	Der Server meldet sich nicht	Nein	Nein
endpoint.backup_overdue	Seit Tagen keine gute Sicherung	Nein	Ja

Die Plattform selbst

Code	Bedeutung	Vorübergehend	Jetzt erneut versuchen
database.unavailable	Die Datenbank war nicht verfügbar	Ja	Ja
database.error	Die Datenbank hat einen Fehler gemeldet	Nein	Ja
directory.conflict	Die Schutzregeln haben sich während des Abgleichs geändert	Ja	Ja
job.interrupted	Der Job wurde unterbrochen	Ja	Ja
unknown	Die Ursache konnte nicht erkannt werden	Nein	Ja