connect_error

Die Funktion mysqli_connect_error() gibt einen string zurück, der den letzten Verbindungsfehler beschreibt, der von MySQLi ausgelöst wurde. Sie ist das erste Mittel der Wahl, wenn mysqli_connect() fehlschlägt und Sie wissen möchten, warum — falscher Host, ungültige Anmeldedaten, fehlende Datenbank oder ein nicht erreichbarer Server. Diese Seite erklärt, was die Funktion zurückgibt, wie sie sich von der verwandten mysqli_connect_errno() unterscheidet und wie sie korrekt in der prozeduralen und objektorientierten MySQLi-API verwendet wird.

Syntax

mysqli_connect_error() nimmt keine Argumente entgegen, da ein fehlgeschlagener Verbindungsversuch per Design kein verwendbares MySQLi-Objekt erzeugt — es gibt also nichts, was übergeben werden könnte.

mysqli_connect_error(): string|null

Rückgabewert

• Ein string mit der menschenlesbaren Fehlermeldung des letzten mysqli_connect()- / mysqli_real_connect()-Aufrufs.
• null wenn kein Fehler aufgetreten ist (die Verbindung erfolgreich war).

Da die Funktion bei Erfolg null zurückgibt, sollten Sie sie nur nach der Bestätigung aufrufen, dass die Verbindung fehlgeschlagen ist.

Verwendung von mysqli_connect_error() (prozeduraler Stil)

In der prozeduralen API gibt mysqli_connect() bei einem Verbindungsfehler false zurück. Prüfen Sie zunächst diesen Rückgabewert und lesen Sie dann die Meldung:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (!$mysqli) {
    // Connection failed — mysqli_connect_error() now holds the reason
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Connected successfully";

// ... run your queries here ...

mysqli_close($mysqli);
?>

Bei falschen Anmeldedaten erscheint eine Ausgabe wie diese:

Failed to connect to MySQL: Access denied for user 'username'@'localhost' (using password: YES)

Objektorientierter Stil: connect_error vs connect_errno

Wenn Sie die Verbindung mit new mysqli(...) erstellen, funktioniert das prozedurale mysqli_connect_error() weiterhin, aber idiomatischer ist es, die entsprechenden Eigenschaften am Objekt zu lesen:

• $mysqli->connect_error — die Fehlermeldung (string oder null bei Erfolg).
• $mysqli->connect_errno — die Fehlernummer (ein ganzzahliger Code, 0 bei Erfolg).

Die Nummer ist nützlich, wenn Sie nach einem bestimmten Fehler verzweigen möchten; die Meldung ist für Menschen und Protokolle gedacht.

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
    exit();
}

echo "Connected successfully";

$mysqli->close();
?>

Eine vollständige Erläuterung des numerischen Codes finden Sie unter mysqli_connect_errno().

Empfehlung: MySQLi Ausnahmen werfen lassen

Das manuelle Prüfen des Rückgabewerts nach jedem Verbindungsaufbau ist leicht zu vergessen. Seit PHP 8.1 wirft MySQLi bei einem Fehler standardmäßig eine mysqli_sql_exception, sodass Sie Fehler mit einem normalen try/catch-Block behandeln können. Dies ist das empfohlene Muster für neuen Code:

<?php
// Enable exception mode explicitly (the default since PHP 8.1)
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
    $mysqli = new mysqli("localhost", "username", "password", "database");
    echo "Connected successfully";
    $mysqli->close();
} catch (mysqli_sql_exception $e) {
    // $e->getMessage() carries the same text connect_error would return
    echo "Failed to connect to MySQL: " . $e->getMessage();
    exit();
}
?>

Mit aktiviertem Ausnahmemodus wird connect_error selten direkt gelesen — die Meldung wird stattdessen innerhalb der Ausnahme weitergegeben.

Häufige Fallstricke

• Rufen Sie die Funktion nicht auf dem Verbindungsobjekt auf, das Sie nicht erhalten haben. Bei einem fehlgeschlagenen prozeduralen Connect ist $mysqli gleich false, sodass $mysqli->connect_error einen Fehler verursachen würde. Verwenden Sie in diesem Fall das eigenständige mysqli_connect_error() (ohne Argument).
• Es spiegelt den letzten Versuch wider. Wenn Sie mehrere Verbindungen öffnen, gehört der Wert zum letzten Connect-Aufruf und nicht zu einem bestimmten Handle.
• Geben Sie in der Produktion niemals rohe Fehlermeldungen an Endbenutzer aus. Verbindungsmeldungen können Hostnamen und Benutzernamen preisgeben — protokollieren Sie diese und zeigen Sie stattdessen eine generische Meldung an.

Fazit

mysqli_connect_error() ist ein kleines, aber unverzichtbares Debugging-Werkzeug: Es teilt Ihnen genau mit, warum eine MySQLi-Verbindung fehlgeschlagen ist. Kombinieren Sie es mit mysqli_connect_errno(), wenn Sie den numerischen Code benötigen, bevorzugen Sie die OO-Eigenschaften connect_error/connect_errno, wenn Sie mit new mysqli() verbinden, und greifen Sie für neue Projekte auf das ausnahmebasierte Fehlerhandling zurück. Weitere Informationen zum Öffnen von Verbindungen finden Sie unter mysqli_connect() und der MySQLi-Übersicht.

Übungen