connect_error

The mysqli_connect_error() function returns a string describing the last connection error raised by MySQLi. It is the first thing you reach for when mysqli_connect() fails and you need to know why — wrong host, bad credentials, missing database, or an unreachable server. This page explains what the function returns, how it differs from the related mysqli_connect_errno(), and how to use it correctly in both the procedural and object-oriented MySQLi APIs.

Syntax

mysqli_connect_error() takes no arguments because, by design, a failed connection attempt does not produce a usable MySQLi object — so there is nothing to pass it.

mysqli_connect_error(): string|null

Return value

• A string with the human-readable error message of the most recent mysqli_connect() / mysqli_real_connect() call.
• null if no error occurred (the connection succeeded).

Because it returns null on success, you should call it only after you have confirmed the connection failed.

How to use mysqli_connect_error() (procedural style)

In the procedural API, mysqli_connect() returns false when the connection fails. Check that return value first, then read the message:

<?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);
?>

If the credentials are wrong you will see something like:

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

Object-oriented style: connect_error vs connect_errno

When you create the connection with new mysqli(...), the procedural mysqli_connect_error() still works, but it is more idiomatic to read the matching properties on the object:

• $mysqli->connect_error — the error message (string, or null on success).
• $mysqli->connect_errno — the error number (an integer code, 0 on success).

The number is handy for branching on a specific failure; the message is for humans and logs.

<?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();
?>

For a full breakdown of the numeric code, see mysqli_connect_errno().

Recommended: let MySQLi throw exceptions

Manually checking the return value after every connect is easy to forget. Since PHP 8.1, MySQLi throws a mysqli_sql_exception on failure by default, which lets you handle errors with a normal try/catch block. This is the recommended pattern for new 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();
}
?>

With exception mode on, connect_error is rarely read directly — the message travels inside the exception instead.

Common gotchas

• Don't call it on the connection object you failed to get. On a failed procedural connect, $mysqli is false, so $mysqli->connect_error would error. Use the standalone mysqli_connect_error() (no argument) in that case.
• It reflects the last attempt. If you open several connections, the value belongs to the most recent connect call, not a specific handle.
• Never echo raw errors to end users in production. Connection messages can leak host names and usernames — log them and show a generic message instead.

Conclusion

mysqli_connect_error() is a small but essential debugging tool: it tells you exactly why a MySQLi connection failed. Pair it with mysqli_connect_errno() when you need the numeric code, prefer the OO connect_error/connect_errno properties when you connect with new mysqli(), and for new projects reach for exception-based error handling. To learn more about opening connections in the first place, see mysqli_connect() and the MySQLi overview.

Practice