Lösungen für: „Fehler beim Aufbau einer Datenbankverbindung“ in WordPress

Wenn Ihre WordPress-Website statt Ihrer Inhalte nur noch den Satz „Fehler beim Aufbau einer Datenbankverbindung“ zeigt, ist das ein Schreck, aber selten ein Verlust. Ihre Beiträge und Seiten sind in aller Regel noch da. WordPress kommt nur gerade nicht an seine Datenbank heran.

Rufen Sie einmal /wp-admin/ auf. Dort sagt WordPress mehr als auf der Website, nämlich ob die Anmeldung an der Datenbank scheitert, ob die Datenbank selbst fehlt oder ob Tabellen fehlen. Meist stimmt danach eine der vier Angaben in der wp-config.php nicht mehr mit denen Ihres Hosters überein, oder der Datenbankserver des Hosters hat eine Störung.

Alles in diesem Beitrag habe ich auf einer Testinstallation (WordPress 7.1.4 auf Deutsch, PHP 8.4, MySQL 8.4) absichtlich kaputt gemacht und wieder repariert: jede Ursache, jeden Befehl, jede Änderung an der wp-config.php. Wo das Ergebnis anders aussieht, als Foren und Anleitungen behaupten, steht das dabei.

Was bedeutet „Fehler beim Aufbau einer Datenbankverbindung“ bei WordPress?

WordPress bewahrt Beiträge, Seiten, Benutzer und Einstellungen in einer Datenbank auf, und zwar in MySQL oder MariaDB. Bei jedem Seitenaufruf meldet es sich dort mit vier Angaben aus der Datei wp-config.php an. Scheitert das, kann es nichts anzeigen und bricht mit dem Statuscode 500 ab.

Es bedeutet nicht, dass Inhalte gelöscht wurden. Und der übliche Griff, alle Plugins abzuschalten, hilft hier nicht: WordPress baut die Verbindung auf, bevor es Plugins und Themes lädt.

Der Wortlaut hängt davon ab, wo Sie die Meldung sehen und welche Version läuft. Gemeint ist immer dasselbe:

• Auf der Website: „Fehler beim Aufbau einer Datenbankverbindung“, im Browser-Tab „Datenbankfehler“.
• Im Dashboard: dieselbe Überschrift, darunter „Das bedeutet entweder, dass der Benutzername und das Passwort in deiner Datei wp-config.php falsch sind, oder dass keine Verbindung zum Datenbankserver unter … hergestellt werden konnte.“
• In älteren Versionen: „Das bedeutet entweder, dass die Information über den Benutzernamen und das Passwort in deiner wp-config.php Datei nicht korrekt ist, oder wir können den Datenbank-Server auf … nicht erreichen.“
• Auf Englisch: „Error establishing a database connection“.

Bevor Sie etwas ändern: Ein falscher Handgriff kann mehr Schaden anrichten als der Fehler selbst. Ein Tippfehler in der wp-config.php legt die ganze Website lahm, ein falscher Befehl in der Datenbank oder auf der Kommandozeile lässt sich oft nicht zurücknehmen. Mit diesen Regeln bleibt jeder Schritt umkehrbar:

• Zuerst eine vollständige Sicherung von Dateien und Datenbank, abgelegt außerhalb Ihres Webspace. Viele Hoster bieten dafür eine eigene Funktion an. Fragen Sie im Zweifel nach, wie Sie die Sicherung wieder einspielen.
• Vor jeder Bearbeitung eine Kopie der Datei auf Ihren eigenen Rechner laden. Eine Kopie auf dem Server darf nicht wp-config.php.bak heißen, denn so kann sie jeder samt Datenbank-Passwort im Browser abrufen. Nennen Sie sie wp-config-kopie.php, und löschen Sie sie am Ende.
• Immer nur eine Änderung, dann testen. Hat sie nicht geholfen, machen Sie sie rückgängig, bevor Sie die nächste versuchen.
• Eine Testkopie (Staging) nutzen, wenn Ihr Hoster eine anbietet: Dort darf alles schiefgehen.
• Aufhören ist eine gute Option: wenn Sie nicht mehr wissen, was Sie geändert haben, wenn ein Schritt anders aussieht als hier beschrieben oder wenn die Website täglich Geld verdient. Dann schreiben Sie mir, das Angebot steht am Ende dieses Beitrags.

Schritt 1: In /wp-admin/ nachsehen, welchen Datenbankfehler WordPress meint

Dafür müssen Sie nichts ändern. Auf der Website sieht jede Ursache gleich aus. In meinem Test haben ein falsches Passwort, ein falscher Datenbankname, ein gestoppter Datenbankserver und eine fehlende Tabelle Byte für Byte dieselbe Seite ergeben. Erst https://ihre-domain.at/wp-admin/ unterscheidet sie:

• „Fehler beim Aufbau einer Datenbankverbindung“ mit dem längeren Text: WordPress kommt gar nicht bis zur Datenbank. In Frage kommen Benutzername, Passwort, Servername, ein Ausfall oder zu viele Verbindungen. Lesen Sie weiter bei Schritt 2.
• „Die Datenbank konnte nicht ausgewählt werden“: Benutzername und Passwort stimmen. Der Datenbankname ist falsch, die Datenbank gibt es nicht mehr, oder der Benutzer hat keine Rechte daran. Lesen Sie bei Schritt 3 den Abschnitt zum Namen.
• „Eine oder mehrere Datenbanktabellen sind nicht verfügbar.“ In älteren Versionen heißt es „… nicht erreichbar“. Die Verbindung steht, aber Daten fehlen oder sind beschädigt. Das ist ein anderes Problem, siehe „Wie kann ich die WordPress-Datenbank reparieren?“ weiter unten.

Schritt 2: Eine Störung beim Hoster als Ursache des WordPress-Datenbankfehlers ausschließen

Fragen Sie sich zuerst, was sich geändert hat: ein neues Passwort, ein Umzug, ein Tarifwechsel, ein abgelaufener Vertrag. Hat sich nichts geändert, ist eine Störung beim Hoster wahrscheinlicher als ein Fehler in Ihren Dateien. Dann sollten Sie auch nichts an der wp-config.php ändern.

• Sehen Sie auf die Störungsseite Ihres Hosters, falls er eine hat.
• Öffnen Sie phpMyAdmin im Kundenbereich. Sehen Sie dort Ihre Tabellen, läuft der Datenbankserver. Meldet auch phpMyAdmin einen Fehler, rufen Sie den Support an. In meinem Test ist phpMyAdmin bei gestopptem Server ebenfalls nicht hineingekommen.

Laut der WordPress-Dokumentation kann der Hoster eine Datenbank auch abschalten, wenn sie ihr Kontingent überschritten hat. Fragen Sie auch danach, wenn Sie beim Support anrufen.

Schritt 3: Die vier Datenbank-Angaben in der wp-config.php von WordPress prüfen

Die Datei wp-config.php liegt im WordPress-Ordner, neben wp-admin und wp-includes. Laden Sie sie per Dateimanager oder FTP herunter und suchen Sie diese vier Zeilen:

define( 'DB_NAME', 'name_der_datenbank' );
define( 'DB_USER', 'benutzername' );
define( 'DB_PASSWORD', 'passwort' );
define( 'DB_HOST', 'servername' );

Vergleichen Sie sie mit den Angaben Ihres Hosters. In Plesk, wie bei meinem eigenen Hosting, finden Sie Name und Benutzer unter Websites & Domains → Dashboard → Datenbanken, den Server dort als „Host“ unter „Informationen zur Verbindung“. Ein Passwort lässt sich dort meist nicht anzeigen, nur neu setzen. Tun Sie das im Kundenbereich, tragen Sie es danach in die wp-config.php ein und warten Sie ein paar Sekunden, bevor Sie urteilen.

Auf diese Dinge kommt es an. Alle habe ich nachgestellt:

• Es ist das richtige Passwort gemeint. Das Datenbank-Passwort ist weder Ihre WordPress-Anmeldung noch der Zugang zum Kundenbereich. Eine neue Anmeldung in der Tabelle wp_users ändert an dieser Meldung nichts. Genau das hatte z.B. ein Betroffener in einem Forum versucht.
• Ein Leerzeichen genügt. Mit einem mitkopierten überflüssigen Leerzeichen am Ende des Passworts habe ich bereits die Fehlermeldung erhalten.
• Sonderzeichen brauchen Aufmerksamkeit. Das Zeichen $ funktioniert zwischen einfachen Anführungszeichen ('pa$$wort'), zwischen doppelten nicht. Ein Apostroph im Passwort muss als \' geschrieben werden. Ohne den Backslash zeigt die Website gar nichts mehr, nur noch Status 500 mit leerer Antwort.
• Beim Namen zählt die Schreibweise und Groß-Kleinschreibung. WP statt wp hat zu „Die Datenbank konnte nicht ausgewählt werden“ geführt. Manche Hoster stellen dem Namen außerdem Ihren Benutzernamen voran, das sagt WordPress in der Meldung selbst. Hat der Datenbank-Benutzer nach einem Import keine Rechte an der neuen Datenbank, sieht die Meldung genauso aus. Weisen Sie ihn im Kundenbereich zu.
• localhost ist nicht überall richtig. Bei meinem Hosting steht in DB_HOST eine interne IP-Adresse mit Port, Strato nennt einen eigenen Servernamen. Übernehmen Sie, was Ihr Hoster angibt.
• Der Rat „localhost durch 127.0.0.1 ersetzen“ hilft nur in einem Fall. localhost verbindet über eine lokale Socket-Datei und ignoriert sogar einen Port, 127.0.0.1 über das Netzwerk. Im Test: Mit MySQL auf demselben Server nur am Netzwerk-Port ist localhost fehlgeschlagen und das war auch bei localhost:3306 der Fall, während 127.0.0.1 funktioniert hat. Bei einer Datenbank auf einem anderen Server hat es nicht geholfen.
• Es ist die richtige Datei. Liegen mehrere WordPress-Ordner auf dem Webspace, wirkt nur die Datei im Ordner dieser Website. Zum Beispiel hatte ein Betroffener in einem Forum die falsche Datei bearbeitet. WordPress liest zwar auch eine wp-config.php einen Ordner höher, aber nur, wenn im eigenen Ordner keine liegt.

Schritt 4: Den genauen Grund für den WordPress-Datenbankfehler im Protokoll finden

Stimmt alles und die Meldung bleibt, sagt einem das Protokoll den Grund, aber welches Protokoll? Hier hilft das Fehlerprotokoll des Hosters nicht: WordPress unterdrückt die Warnung, in meinem Test war dort nach dem Fehler keine einzige Zeile zu sehen. Sie brauchen also das WordPress-eigene Protokoll. Ändern Sie in der wp-config.php die vorhandene Zeile define( 'WP_DEBUG', false ); auf true, und ergänzen Sie darunter die anderen beiden, oberhalb von „Das war’s, Schluss mit dem Bearbeiten!“:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Rufen Sie die Website auf und öffnen Sie wp-content/debug.log. Die Zeile beginnt mit mysqli_real_connect(), entscheidend ist, was danach kommt:

• Access denied for user … (using password: YES): Benutzername oder Passwort stimmt nicht, oder den Benutzer gibt es nicht mehr.
• getaddrinfo for … failed: Den Servernamen in DB_HOST gibt es nicht.
• Connection refused: Der Server antwortet an dieser Adresse nicht. Der Port ist falsch, oder die Datenbank läuft nicht.
• No such file or directory: DB_HOST steht auf localhost, aber die Socket-Datei fehlt.
• max_user_connections oder Too many connections: Das Limit an Verbindungen ist erreicht, siehe den übernächsten Abschnitt.

Bleibt die Datei leer, gehört Ihr Fall zu den beiden anderen Meldungen aus Schritt 1: Ein falscher Datenbankname hat im Test nichts ins Protokoll geschrieben.

Zwei Warnungen. Die dritte Zeile ist nicht optional: Ohne sie haben im Test alle Besucher den Datenbank-Benutzer und den Serverpfad mit Status 200 gesehen. Und debug.log kann jeder im Browser abrufen. Nehmen Sie die Zeilen wieder heraus und löschen Sie die Datei, sobald Sie den Grund kennen.

Das Testskript aus vielen Anleitungen (mysqli_connect mit die()) hilft übrigens nicht mehr: Unter PHP 8.4 liefert es bei falschem Passwort nur Status 500 und eine leere Seite. Wollen Sie neue Zugangsdaten prüfen, ohne die wp-config.php anzufassen, funktioniert diese Fassung. Speichern Sie sie mit Ihren Werten unter einem schwer zu erratenden Namen im WordPress-Ordner, rufen Sie sie auf und löschen Sie sie sofort wieder, denn das Passwort steht drin:

<?php
mysqli_report( MYSQLI_REPORT_OFF );
$c = @mysqli_connect( 'servername', 'benutzername', 'passwort', 'name_der_datenbank' );
echo $c ? 'Verbindung klappt' : mysqli_connect_errno() . ': ' . mysqli_connect_error();

Die Antwort ist „Verbindung klappt“ oder der Grund, zum Beispiel 1045: Access denied …. Mit 1044 sind Benutzername und Passwort richtig, aber der Name der Datenbank oder die Rechte daran nicht.

Mit SSH-Zugang geht es ohne Datei. WP-CLI selbst verrät den Grund nicht, es meldet nur denselben Satz, kann aber die Werte auslesen:

wp config get DB_HOST
mysql -h servername -u benutzername -p name_der_datenbank

Die üblichen Ursachen für einen Datenbankfehler in WordPress

Nach einem Umzug oder Hosterwechsel

Die Datenbank hat auf dem neuen Server meist einen anderen Namen, Benutzer und Server. Bleibt die alte wp-config.php stehen, kommt genau diese Meldung.

Das Passwort wurde beim Hoster geändert

Ein neues Datenbank-Passwort im Kundenbereich gilt sofort, die Website kennt aber nur das alte. Ändern Sie immer beide Stellen im selben Arbeitsgang.

Der Datenbankserver ist ausgefallen oder nicht erreichbar

Gestoppt hat mein Test-Datenbankserver sofort die entsprechende Meldung ergeben. Antwortet die Adresse in DB_HOST gar nicht, lädt die Seite zuerst sehr lange: Im Test war die Meldung erst nach 60 Sekunden da. Beides kann nur der Hoster beheben, wenn die Adresse stimmt.

Eine Datei wp-content/db.php leitet die Verbindung um

Manche Plugins legen eine Datei wp-content/db.php an, die den Datenbankzugriff von WordPress ersetzt. Zeigt sie auf einen falschen Server, kommt in meinem Test dieselbe Meldung, auch wenn die wp-config.php stimmt. Liegt eine solche Datei dort, benennen Sie sie versuchsweise um.

Warum erscheint der WordPress-Datenbankfehler nur manchmal?

Mal läuft die Website, mal nicht: Das spricht für ein Limit an gleichzeitigen Verbindungen. Beide Limits habe ich nachgestellt, das des einzelnen Benutzers (max_user_connections) und das des ganzen Servers (max_connections). Der Text im Dashboard führt dabei in die Irre: Er spricht von falschem Benutzernamen und Passwort, obwohl beides stimmt. Nur debug.log nennt das Limit.

Fragen Sie Ihren Hoster, wo das Limit liegt und ob er in den Protokollen sieht, wer die Verbindungen belegt. In einem gelösten Forenfall z.B. hat der Betreiber die Ursache beim Ein- und Ausschalten der Plugins gefunden: Ein Plugin hat in diesem Fall massenhaft Aufrufe einer nicht vorhandenen Datei protokolliert. Das Limit mag zwar der Grund sein, die eigentliche Ursache für den Fehler ist dann aber oft einfach nur etwas, das zu viele Aufrufe erzeugt.

Warum geht die WordPress-Startseite noch, aber wp-admin zeigt den Datenbankfehler?

Meist ist das der Seiten-Cache. Im Test mit WP Super Cache hat die zwischengespeicherte Startseite bei kaputter Verbindung weiter Status 200 geliefert, weil sie die Datenbank gar nicht mehr braucht. Alle anderen Seiten, die Anmeldung und das Dashboard haben den Fehler aber gezeigt.

Behandeln Sie das wie den Totalausfall, die Schritte sind dieselben. Und leeren Sie den Cache erst, wenn die Verbindung wieder steht. Bis dahin sind die gespeicherten Seiten alles, was Ihre Besucher noch sehen.

Warum zeigt WordPress statt des Datenbankfehlers plötzlich die Installation?

Füllen Sie das Formular nicht aus. Sie sehen „Willkommen bei der berühmten 5-Minuten-Installation von WordPress“, weil die Verbindung zwar steht, WordPress aber keine Tabellen findet. Dafür gibt es zwei Gründe:

• $table_prefix in der wp-config.php passt nicht. Die Vorsilbe muss der Ihrer Tabellen entsprechen, die Sie in phpMyAdmin sehen (etwa wp_). Per SSH nennt wp option get home die gefundene Vorsilbe. Ich habe das Formular im Test trotzdem ausgefüllt: Es ist dabei eine leere neue Website durch zusätzliche Tabellen entstanden, die alten sind unberührt geblieben, und mit der richtigen Vorsilbe war alles wieder da.
• DB_NAME zeigt auf eine leere Datenbank. Dann tragen Sie den richtigen Namen ein. Ist Ihre Datenbank wirklich leer, hilft nur die Wiederherstellung einer bereits vorhandenen Sicherung.

Sehen Sie stattdessen „Bevor du loslegst“ und eine Abfrage der Datenbank-Angaben, fehlt die wp-config.php. Spielen Sie Ihre Kopie aus einem Backup zurück.

Lautet die Meldung „Deine PHP-Installation scheint nicht über die von WordPress benötigte MySQL-Erweiterung zu verfügen.“, ist es ebenfalls kein Verbindungsproblem. Die Erweiterung mysqli ist nicht aktiv. Schalten Sie sie in den PHP-Einstellungen Ihres Hosters ein oder fragen Sie dort nach.

Wie kann ich die WordPress-Datenbank reparieren?

Eine Reparatur kommt nur in Frage, wenn /wp-admin/ „Eine oder mehrere Datenbanktabellen sind nicht verfügbar“ meldet. Das kann auch hinter der gewohnten Zeile auf der Website stecken: Im Test haben eine fehlende Tabelle wp_options und schon eine in der Tabelle fehlende Zeile siteurl zu derselben Meldung wie ein falsches Passwort geführt.

WordPress bringt dafür die Zeile define( 'WP_ALLOW_REPAIR', true ); für die wp-config.php mit, danach ist unter /wp-admin/maint/repair.php eine Reparaturseite erreichbar, ohne Anmeldung und für jeden. Nehmen Sie die Zeile gleich danach wieder heraus. Eine fehlende Tabelle stellt sie nicht wieder her: „Die Reparatur der Tabelle wp_options ist fehlgeschlagen.“ Dann hilft nur die Wiederherstellung einer Sicherung. Bevor Sie aber an einer beschädigten Datenbank weiterarbeiten, sichern Sie sie und fragen Sie Ihren Hoster. Wie Sie beschädigte Tabellen reparieren, eine Sicherung einspielen oder die Website ohne Sicherung wiederherstellen, beschreibe ich in meinem Artikel Lösungen für: WordPress-Website komplett kaputt.

Wenn nichts davon hilft

• Fragen Sie Ihren Hoster, und zwar konkret: Läuft der Datenbankserver? Stimmen Datenbankname, Benutzer und Server? Hat der Benutzer Rechte? Ist ein Limit oder Kontingent erreicht? Er sieht, was Sie nicht sehen.
• Spielen Sie eine Sicherung ein, wenn Daten fehlen. Bei falschen Zugangsdaten nützt eine Sicherung der Datenbank allein nichts, denn dann kommt WordPress auch an die zurückgespielte Datenbank nicht heran. Was seit der Sicherung geändert wurde, geht verloren.
• Fragen Sie mich. Schreiben Sie mir, was unter /wp-admin/ steht. Das Angebot steht gleich unter diesem Beitrag.

Dieser Beitrag behandelt Verbindungsprobleme, keine Hacks. Sehen Sie im Protokoll Dateien oder Plugins, die Sie nie installiert haben, wenden Sie sich an Ihren Hoster (oder an mich), statt weiter zu probieren.

Damit es beim nächsten Mal schneller geht

• Halten Sie die Datenbank-Angaben griffbereit, außerhalb des Webspace in Ihrem Passwort-Manager, und ändern Sie ein Datenbank-Passwort immer zugleich in der wp-config.php.
• Lassen Sie mehr als die Startseite überwachen. Der Cache kann den Ausfall dort verbergen. Meine eigene Überwachung sucht zusätzlich nach genau diesem Fehlertext. Was sonst noch zur Pflege gehört, steht in WordPress-Website richtig pflegen.
• Hinterlegen Sie eine eigene Hinweisseite. Eine Datei wp-content/db-error.php ersetzt die Meldung. Ohne weitere Angabe antwortet sie aber mit Status 200, Suchmaschinen können sie also für Ihren Inhalt halten. Beginnen Sie sie deshalb mit dieser Zeile, dann lautet der Status 503. Sie ersetzt auch die Meldung unter /wp-admin/, nehmen Sie sie bei der Fehlersuche also kurz weg:

<?php http_response_code( 503 ); header( 'Retry-After: 600' ); ?>

Zeigt die Website dagegen „Auf dieser Website ist ein kritischer Fehler aufgetreten“, ist es ein PHP-Absturz und kein Datenbankproblem: Dafür gibt es Lösungen für: kritischer Fehler und weiße Seite.