Nextcloud WebGUI-Fehler „Datenbankfehler“ nach einem Update beheben: Praktischer Leitfaden zur Fehlerbehebung

Eine Nextcloud-WebGUI-Meldung wie „Ausnahme: Datenbankfehler“ direkt nach einem Update bedeutet in der Regel, dass die Webanwendung zwar bis zur Datenbankebene geladen werden konnte, aber eine Abfrage, Migration, Schemaerwartung, Verbindung oder ein anwendungsspezifischer Datenbankvorgang fehlschlägt. Löschen Sie nicht sofort Tabellen, installieren Sie Nextcloud nicht neu und stellen Sie kein altes Codeverzeichnis über das neue wieder her. Gehen Sie stattdessen sicherer vor: Identifizieren Sie die fehlerhafte SQL-Anweisung oder Migration, schließen Sie den unterstützten Update-Pfad ab, reparieren Sie nur die von Nextcloud reparierten Fehler und überprüfen Sie den Datenbankdienst und das Schema, bevor Sie den Zugriff wiederherstellen.

Diese Referenz orientiert sich an der aktuellen Nextcloud-35-Administrationsdokumentation (Stand: Oktober 2026). Die folgenden Befehle setzen eine gängige Debian/Ubuntu-Installation mit /var/www/nextclouddem Webserver-Benutzer voraus www-data. Passen Sie Pfad, PHP-Datei, Container-Befehl oder HTTP-Benutzer an Ihre Umgebung an.

Kurzdiagnose: Worauf der Fehler üblicherweise hinweist

1. Den aktuellen Zustand vor Datenbankänderungen sichern.

Falls Sie noch ein Backup vor dem Update besitzen, lassen Sie es unverändert. Nextcloud empfiehlt ausdrücklich, vor jedem Update ein Backup zu erstellen. Das integrierte Updater-Backup sichert zwar die Codebasis, jedoch nicht die Datenbank oder das Datenverzeichnis . Falls Sie kein aktuelles Datenbank-Backup haben, erstellen Sie eines mit dem üblichen Backup-Tool Ihrer Datenbankplattform, bevor Sie manuelle SQL-Änderungen oder -Wiederherstellungen vornehmen.

Vermeiden Sie ein Downgrade als schnelle Lösung. Nextcloud weist darauf hin, dass Downgrades nicht unterstützt werden und Daten beschädigen können. Sollte ein Rollback dennoch notwendig sein, ist die empfohlene Wiederherstellungsmethode eine Neuinstallation der älteren Version mit anschließender Wiederherstellung eines passenden Backups. Das Kopieren alter Programmdateien in eine Datenbank, deren Migration bereits begonnen hat, ist nicht zulässig. Weitere Informationen finden Sie in der Dokumentation zum integrierten Updater von Nextcloud .

2. Lesen Sie die genaue Datenbankausnahme im Nextcloud-Protokoll.

Bei aktivierter Dateiprotokollierung befindet sich das Standardprotokoll nextcloud.logim konfigurierten Datenverzeichnis. Die Fehlerbehebungsanleitung von Nextcloud empfiehlt, dieses Protokoll sowie gegebenenfalls die Webserver- und PHP-Protokolle zu überprüfen. Falls auf der Fehlerseite eine Anfrage-ID angezeigt wird, suchen Sie nach dieser ID, um die entsprechende Transaktion zu identifizieren.

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

Beschränken Sie den Protokolleintrag nicht auf die Meldung „Datenbankfehler“. Erfassen Sie den SQLSTATE-Code, die Ausnahmeklasse, die fehlerhafte Tabelle oder Spalte sowie die im Stacktrace genannte Anwendung oder Kernkomponente. Beispielsweise ist „Tabelle existiert nicht“ ein völlig anderer Fehler als „Zu viele Verbindungen“ oder „MySQL-Server nicht erreichbar“. Nextcloud listet in seiner allgemeinen Dokumentation zur Fehlerbehebung mehrere häufige SQLSTATE-Fehler auf .

3. Überprüfen Sie, ob das Update tatsächlich abgeschlossen ist.

Der integrierte Updater ersetzt zuerst den Nextcloud-Code. Datenbank- und App-Migrationen erfolgen in einem separaten Schritt. Im Kommandozeilenmodus kann der Updater occ upgradeautomatisch ausgeführt werden; andernfalls muss die Migration anschließend noch abgeschlossen werden. Diese Unterscheidung erklärt viele Fälle, in denen der Updater zwar als „abgeschlossen“ angezeigt wurde, die normale WebGUI jedoch eine Datenbankausnahme zurückgibt.

cd /var/www/nextcloud
sudo -E -u www-data php occ status

Wenn Sie die Instanz während der Fehlerbehebung schützen müssen, aktivieren Sie den Wartungsmodus. Nextcloud beschreibt den Wartungsmodus als den für Upgrades vorgesehenen Modus, da er neue Anmeldungen verhindert und aktive Sitzungen sperrt.

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

4. Schließen Sie die unterstützten Datenbank- und Anwendungsmigrationen mit occ upgrade ab.

Falls der Code aktualisiert wurde, die Migrationen aber nicht abgeschlossen wurden, führen Sie den Upgrade-Befehl als HTTP-Benutzer aus:

cd /var/www/nextcloud
sudo -E -u www-data php occ upgrade

Beobachten Sie die Ausgabe, bis der Befehl entweder erfolgreich ausgeführt wird oder aufgrund eines Fehlers abbricht. Beheben Sie im Fehlerfall die entsprechende Voraussetzung, bevor Sie den Befehl wiederholen. Typische Fehlerquellen sind inkompatible Anwendungen, nicht unterstützte PHP-/Datenbankversionen, nicht verfügbare Datenbankdienste oder Berechtigungen, die die erforderlichen Aktualisierungen verhindern. Aktualisieren Sie die WebGUI nicht wiederholt, solange die Migration fehlschlägt.

Die Upgrade-Dokumentation von Nextcloud warnt ebenfalls davor, Hauptversionen zu überspringen. Aktualisieren Sie bei einem Wechsel zwischen Hauptversionen immer nur auf eine Version nach der anderen.

5. Führen Sie die Reparaturfunktion von Nextcloud aus, nachdem das Migrationsproblem behoben wurde.

maintenance:repairFührt Reparaturschritte für Nextcloud aus und wird auch bei Aktualisierungen automatisch ausgeführt. Eine manuelle Ausführung ist sinnvoll, nachdem Sie die Ursache für die Unterbrechung der Aktualisierung behoben haben:

sudo -E -u www-data php occ maintenance:repair

Dies ist sicherer als das Erstellen eigener SQL-Anweisungen, da die Reparaturschritte von Nextcloud Core und den Apps bereitgestellt werden. Es ist kein Allheilmittel occ upgradeund kann weder einen ausgefallenen Datenbankserver noch eine nicht unterstützte Datenbankversion reparieren. Der Befehl ist in der Dokumentation zu Nextcloud-System- und Wartungsbefehlen beschrieben .

6. Überprüfen Sie den Datenbankdienst, die Verbindungseinstellungen und die unterstützte Version.

Wenn das Protokoll auf Verbindungsprobleme anstatt auf ein Schemaproblem hinweist, überprüfen Sie, ob der Datenbankdienst ausgeführt wird und von der Nextcloud-PHP-Umgebung aus erreichbar ist. Auf einem typischen MariaDB-Host ist folgender Test hilfreich:

sudo systemctl status mariadb

Überprüfen Sie anschließend die Datenbankeinstellungen config/config.php: Datenbanktyp, Host, Datenbankname, Benutzer und alle Socket- oder Port-Einstellungen. Ein Unix-Socket-Fehler kann beispielsweise als „Datei oder Verzeichnis nicht gefunden“ angezeigt werden, während der Zugriff auf eine Remote-Datenbank aufgrund von Routing-, DNS-, TLS-, Firewall-Regeln, Anmeldeinformationen oder Serverproblemen selbst fehlschlagen kann.

Die Versionskompatibilität ist nach einem größeren Nextcloud-Update wichtig. In den offiziellen Versionshinweisen zu Nextcloud 35 wird darauf hingewiesen, dass MariaDB 10.6 und MySQL 8.0 nicht mehr unterstützt werden; die dokumentierten Mindestanforderungen sind MariaDB 10.11 LTS und MySQL 8.4 LTS. Prüfen Sie die Anforderungen für Ihre genaue Nextcloud-Hauptversion, bevor Sie die Datenbank separat aktualisieren. Weitere Informationen finden Sie unter „Upgrade auf Nextcloud 35“ .

7. Überprüfen Sie die Schemaabweichung und fügen Sie nur die dokumentierten fehlenden Strukturen hinzu.

Nextcloud 35 führt eine Funktion ein db:schema:check, die das aktuelle Schema mit dem von den installierten Core- und App-Migrationen erwarteten Schema vergleicht. Diese Funktion ist schreibgeschützt: Sie meldet Unterschiede, ohne die Datenbank zu verändern.

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

Falls die Administratorübersicht oder die Befehlsausgabe fehlende optionale Spalten, Indizes oder Primärschlüssel meldet, verwenden Sie die dokumentierten Wartungsbefehle:

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

Jeder Befehl unterstützt --dry-rundie SQL-Vorschau. Diese Befehle sollten nicht als Ersatz für eine fehlgeschlagene Kernmigration verwendet werden. Falls db:schema:checkunerwartete Objekte oder Unterschiede in Spalteneigenschaften gemeldet werden, überprüfen Sie die Ergebnisse, bevor Sie Änderungen vornehmen. Nextcloud weist darauf hin, dass einige datenbankweite Standardwerte außerhalb des erwarteten Schemamodells liegen. Die maßgebliche Befehlsreferenz finden Sie unter Nextcloud DAV- und Datenbankbefehle .

8. Beheben Sie Fehler in Drittanbieter-Apps, bevor Sie die WebGUI erneut öffnen.

Wenn der Stacktrace eine nicht standardmäßig ausgelieferte Anwendung nennt, ist deren Migration möglicherweise nicht mit der neuen Serverversion kompatibel. Nextclouds Leitfaden zur Fehlerbehebung empfiehlt, Drittanbieter-Apps/nicht standardmäßig ausgelieferte Anwendungen für Upgrades und zur Fehlerbehebung zu deaktivieren. Verwenden Sie die in Ihrer installierten Version verfügbaren App-Befehle, um die betreffende Anwendung über die Befehlszeile zu deaktivieren, führen Sie den Befehl erneut aus occ upgradeund aktivieren Sie die Anwendung erst wieder, nachdem Sie eine kompatible Version bestätigt haben.

Dieser Zweig ist besonders wichtig, wenn die Kerntabellen intakt erscheinen, die Ausnahme aber einen Anbieter-Namespace oder eine Tabelle einer bestimmten Anwendung betrifft. Das manuelle Entfernen der Tabellen dieser Anwendung ist riskant, da dadurch Daten zerstört werden könnten, die die Anwendung noch benötigt.

9. Beenden Sie den Wartungsmodus und überprüfen Sie mehr als nur die Anmeldeseite.

Nach occ upgradeAbschluss der Reparatur-/Schemaprüfungen wird kein blockierendes Problem mehr angezeigt, und der Datenbankdienst ist stabil. Deaktivieren Sie den Wartungsmodus:

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

Überprüfen Sie anschließend die Instanz schrittweise: Laden Sie die Anmeldeseite, melden Sie sich an, öffnen Sie „Dateien“, durchsuchen Sie einige Ordner, testen Sie das Hoch- und Herunterladen einer Datei, prüfen Sie die Administrationseinstellungen auf Warnungen und die neuesten nextcloud.logEinträge. Stellen Sie außerdem sicher, dass Cron-Jobs und Hintergrundprozesse ordnungsgemäß ausgeführt werden. Eine wiederhergestellte Startseite allein beweist nicht, dass Anwendungsmigrationen, Dateivorgänge und Hintergrundprozesse einwandfrei funktionieren.

Wiederherstellungs-Checkliste

• Bewahren Sie die Sicherung vor dem Update auf und vermeiden Sie ein nicht unterstütztes Downgrade.
• Lesen Sie die vollständige Datenbankausnahme in nextcloud.log, einschließlich SQLSTATE und der im Trace genannten Komponente.
• Prüfen Sie occ status, ob die Instanz während der Reparatur in den Wartungsmodus versetzt werden kann.
• Führen Sie den Befehl aus occ upgrade, um die unterstützten Core- und Anwendungsmigrationen abzuschließen.
• Beheben Sie das erste konkrete Problem, anstatt Datenbanktabellen blind zu bearbeiten.
• Führen Sie dieses Programm aus maintenance:repair, nachdem der zugrunde liegende Fehler behoben wurde.
• Überprüfen Sie den Zustand des Datenbankdienstes, die Verbindungseinstellungen und die Versionskompatibilität.
• Verwenden Sie db:schema:checkNextcloud 35 und die dokumentierten db:add-missing-*Befehle, wo dies angebracht ist.
• Deaktivieren Sie eine fehlerhafte Drittanbieter-App, wenn die Ablaufverfolgung eindeutig darauf hinweist, und versuchen Sie dann das Upgrade erneut.
• Schalten Sie den Wartungsmodus erst aus, nachdem die CLI-Prüfungen erfolgreich waren. Testen Sie anschließend Dateien, Übertragungen, Administratorwarnungen, Protokolle und Hintergrundprozesse.

Wann man wiederherstellen statt reparieren sollte.

Stellen Sie die Datenbank aus einem bekannten, intern konsistenten Backup wieder her, wenn die Datenbank selbst beschädigt ist, Migrationen Daten teilweise so verändert haben, dass dies nicht gefahrlos rückgängig gemacht werden kann, oder wenn benötigte Tabellen/Daten außerhalb von Nextcloud gelöscht wurden. Datenbank, Konfiguration, Datenverzeichnis und Codeversion müssen zu einem kompatiblen Wiederherstellungspunkt gehören. Wenn Sie kostenpflichtigen Nextcloud-Support nutzen oder eine geschäftskritische Bereitstellung haben, brechen Sie den Vorgang ab, bevor Sie destruktive SQL-Operationen durchführen, und eskalieren Sie den Support mit dem vollständigen Logeintrag, den genauen Quell- und Zielversionen von Nextcloud, dem Datenbanktyp/-version, der PHP-Version und der Ausgabe des relevanten occBefehls.

Das Grundprinzip ist einfach: Ein „Datenbankfehler“ nach einem Update ist kein Grund, SQL-Anweisungen zu erraten. Lassen Sie das Protokoll den Fehler identifizieren, lassen Sie occ upgradedie geplanten Migrationen abschließen, verwenden Sie die Reparatur- und Schema-Tools von Nextcloud und validieren Sie die Datenbankplattform, bevor Sie die Instanz wieder öffnen.