Nextcloud occ maintenance:repair: Fehlermeldungen und Warnungen verstehen und beheben

Kein Kommentar Autor: Jürgen (jdo)

Mit occ maintenance:repair reparierst Du eine Nextcloud-Installation über die Kommandozeile. Normalerweise musst Du den Befehl gar nicht ausführen, da ihn das System automatisch bei Upgrades ausführt, um die Datenbank zu bereinigen. Von Hand lohnt er sich, wenn Du einen Fehler eingrenzen willst. Die Datenbank-Warnungen in der Verwaltungsübersicht behebst Du dagegen meist mit eigenen occ-Befehlen.

So rufst Du occ maintenance:repair auf

occ liegt im Verzeichnis der Nextcloud, unter Debian und Ubuntu zum Beispiel in /var/www/nextcloud. Starte es immer als Benutzer des Webservers, damit Besitzer und Rechte der Dateien stimmen. Unter Debian und Ubuntu ist das www-data, unter Fedora apache und unter Arch Linux http.

cd /var/www/nextcloud
sudo -u www-data php occ maintenance:repair

In Containern und Paketen sieht der Aufruf anders aus:

  • Offizielles Docker-Image: docker exec -it --user www-data CONTAINER_ID php occ maintenance:repair
  • Nextcloud AIO: sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ maintenance:repair
  • Snap: sudo nextcloud.occ maintenance:repair

Was maintenance:repair macht

Der Befehl führt die Reparaturschritte von Nextcloud und allen aktivierten Apps aus. Jeder Schritt erscheint als eigene Zeile. Warnungen beginnen mit WARNING und sind gelb, echte Fehler beginnen mit ERROR und sind rot. Gibt es einen Fehler, endet der Befehl mit dem Rückgabewert 1.

Während der Reparatur schaltet maintenance:repair den Wartungsmodus selbst ein. Danach stellt er den vorherigen Zustand wieder her. Du musst die Nextcloud also nicht vorher in den Wartungsmodus versetzen.

Aufwendige Schritte laufen nur mit dem Schalter --include-expensive. Auf großen Instanzen kann das dauern. Starte den Befehl deshalb zu einer ruhigen Zeit:

sudo -u www-data php occ maintenance:repair --include-expensive

Rote Fehler: „Failed to load repair step … is unknown“

Viel Rot muss außerdem nicht gleich immer viele Probleme bedeuten. Das zeigte sich 2019 bei maintenance:repair. Bei der Wartung einer Nextcloud-Instanz wurde der Befehl sudo -u www-data php occ maintenance:repair aufgerufen. Das hat folgende Fehlermeldungen zur Folge gehabt und die auch noch in warnendem Rot, wie Du am Screenshot im Anschluss siehst.

Failed to load repair step for dav: Repair step 'OCA\DAV\Migration\FixBirthdayCalendarComponent' is unknown
Failed to load repair step for dav: Repair step 'OCA\DAV\Migration\CalDAVRemoveEmptyValue' is unknown
Failed to load repair step for dav: Repair step 'OCA\DAV\Migration\BuildCalendarSearchIndex' is unknown
Failed to load repair step for dav: Repair step 'OCA\DAV\Migration\RefreshWebcalJobRegistrar' is unknown
Failed to load repair step for dav: Repair step 'OCA\DAV\Migration\RemoveClassifiedEventActivity' is unknown
Failed to load repair step for files_sharing: Repair step 'OCA\Files_Sharing\Migration\OwncloudGuestShareType' is unknown
Failed to load repair step for files_sharing: Repair step 'OCA\Files_Sharing\Migration\SetPasswordColumn' is unknown
Failed to load repair step for oauth2: Repair step 'OCA\OAuth2\Migration\SetTokenExpiration' is unknown
Failed to load repair step for twofactor_backupcodes: Repair step 'OCA\TwoFactorBackupCodes\Migration\CheckBackupCodes' is unknown
maintenance:repair bei der Nextcloud bringt im Wartungsmodus viele Fehlermeldungen
maintenance:repair bei der Nextcloud bringt viele Fehlermeldungen (Aufnahme von 2019)

Das löst auf den ersten Blick ziemliches Unbehagen aus und wird gedanklich mit einem WTF?! garniert.

Damals war der Wartungsmodus schuld

Weil Wartung schnell mit dem Wartungsmodus verbunden wird, wurde die Nextcloud damals vor irgendwelchen Befehlen in eben jenen versetzt:

sudo -u www-data php occ maintenance:mode --on

Oberhalb der Fehlermeldungen war aber auch in einer Art Orange unterlegt:

Nextcloud is in maintenance mode - no apps have been loaded

Im Wartungsmodus lädt occ keine Apps. Deshalb fand maintenance:repair die Reparaturschritte von dav, files_sharing, oauth2 und den Backup-Codes nicht. Nach dem Abschalten des Wartungsmodus lief der Befehl abermals, und es gab keine Probleme mehr. Abgeschaltet wird er so:

sudo -u www-data php occ maintenance:mode --off

Damals wurde ein Fehler gesucht, und man wollte eben alle Eventualitäten ausschließen. Deswegen wurde maintenance:repair manuell durchgeführt. Der Fehler? Hat sich im Endeffekt als User herausgestellt.

Was heute gilt

Die roten Meldungen gingen auf einen Fehler in Nextcloud zurück, gemeldet im April 2019 als Issue 15042. Seit Nextcloud 14.0.11, 15.0.8 und 16 lädt maintenance:repair die Apps vor den Reparaturschritten selbst. Siehst Du die Meldungen trotzdem, prüfe mit sudo -u www-data php occ status die Zeile maintenance und aktualisiere eine sehr alte Installation.

Den Wartungsmodus brauchst Du dafür nicht. Das Nextcloud-Handbuch zu occ rät davon ab, solange ein Befehl oder seine Doku ihn nicht ausdrücklich verlangt. Im Wartungsmodus fehlen die Befehle der Apps, und Apps reagieren nicht auf Ereignisse. Löschst Du dann etwa einen Benutzer, bleiben seine Kalenderdaten liegen.

Warnungen in der Übersicht: die passenden occ-Befehle

In den Administrationseinstellungen listet Nextcloud unter Übersicht die Sicherheits- & Einrichtungswarnungen. Die meisten der folgenden Meldungen betreffen die Datenbank. Nextcloud erledigt diese Arbeiten bei Upgrades bewusst nicht, weil sie auf großen Tabellen lange dauern können. Mach vorher ein Backup der Datenbank.

„In der Datenbank fehlen Indizes“

Neue Indizes beschleunigen Abfragen, ihr Anlegen kann die Leistung aber kurz drücken. Mit --dry-run siehst Du vorher die SQL-Befehle:

sudo -u www-data php occ db:add-missing-indices --dry-run
sudo -u www-data php occ db:add-missing-indices

„In der Datenbank fehlen Spalten“ oder „Primärschlüssel“

Beides holst Du nach, während die Instanz weiterläuft:

sudo -u www-data php occ db:add-missing-columns
sudo -u www-data php occ db:add-missing-primary-keys

„Datenbank mit ausstehenden Bigint-Migrationen“

Hier stellt Nextcloud ID-Spalten auf den Typ BigInt um. Laut der Warnung muss die Instanz dafür offline sein. Hier passt der Wartungsmodus. Der Befehl zeigt die betroffenen Spalten, warnt vor einer Laufzeit von bis zu mehreren Stunden und fragt vor dem Start nach.

sudo -u www-data php occ maintenance:mode --on
sudo -u www-data php occ db:convert-filecache-bigint
sudo -u www-data php occ maintenance:mode --off

„MIME-Type-Migrationen verfügbar“

Neue Dateitypen ordnet Nextcloud beim Upgrade nicht zu, weil das auf großen Instanzen lange dauert. Diese Warnung behebst Du mit maintenance:repair und dem Schalter für aufwendige Schritte.

sudo -u www-data php occ maintenance:repair --include-expensive

„Beginn des Wartungsfensters“

Ohne Wartungsfenster laufen aufwendige tägliche Hintergrundjobs auch zur Hauptnutzungszeit. Der Wert ist eine Stunde in UTC, das Fenster dauert vier Stunden. Mit 1 laufen diese Jobs zwischen 01:00 und 05:00 Uhr UTC.

sudo -u www-data php occ config:system:set maintenance_window_start --type=integer --value=1

Datenbankschema prüfen mit db:schema:check

Seit Nextcloud 35 vergleicht occ db:schema:check die Datenbank mit dem Schema, das Nextcloud und Deine Apps erwarten. Der Befehl ändert nichts. Er meldet fehlende oder unerwartete Tabellen, Spalten und Indizes. Nicht jede Abweichung ist ein Fehler, prüfe die Funde deshalb vor jeder Änderung. Alle Datenbank-Befehle beschreibt das Handbuch.

sudo -u www-data php occ db:schema:check

Nextcloud AIO und andere Fehler nach Updates

Nextcloud AIO führt nach einem Update selbst maintenance:repair --include-expensive aus. Dazu kommen die Befehle für fehlende Indizes, Spalten und Primärschlüssel sowie die BigInt-Umstellung. Mit NEXTCLOUD_SKIP_DATABASE_OPTIMIZATION=yes läuft nur das einfache maintenance:repair. Willst Du Dich um solche Wartung gar nicht kümmern, schau Dir das Nextcloud-Hosting an.

Nicht jeder Ärger nach einem Update ist ein Fall für maintenance:repair. Lassen sich in der Nextcloud Ordner nicht löschen, hilft eine eigene Anleitung weiter. Öffnet Nextcloud Office nach einem Update keine Dokumente mehr, lies den Beitrag zum integrierten Collabora Online.

Aktualisiert am 18.10.2026 von Henry. Fakten geprüft.




 Alle Kommentare als Feed abonnieren

Antworten