connect_error

La función mysqli_connect_error() devuelve una string que describe el último error de conexión generado por MySQLi. Es lo primero a lo que recurres cuando mysqli_connect() falla y necesitas saber por qué — host incorrecto, credenciales erróneas, base de datos inexistente o un servidor inaccesible. Esta página explica qué devuelve la función, en qué se diferencia de la función relacionada mysqli_connect_errno(), y cómo usarla correctamente tanto en la API MySQLi procedural como en la orientada a objetos.

Sintaxis

mysqli_connect_error() no acepta argumentos porque, por diseño, un intento de conexión fallido no produce un objeto MySQLi utilizable — así que no hay nada que pasarle.

mysqli_connect_error(): string|null

Valor de retorno

• Una string con el mensaje de error legible por humanos de la llamada más reciente a mysqli_connect() / mysqli_real_connect().
• null si no ocurrió ningún error (la conexión fue exitosa).

Dado que devuelve null cuando tiene éxito, deberías llamarla solo después de haber confirmado que la conexión falló.

Cómo usar mysqli_connect_error() (estilo procedural)

En la API procedural, mysqli_connect() devuelve false cuando la conexión falla. Comprueba primero ese valor de retorno y luego lee el mensaje:

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

Si las credenciales son incorrectas, verás algo como:

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

Estilo orientado a objetos: connect_error vs connect_errno

Cuando creas la conexión con new mysqli(...), el mysqli_connect_error() procedural sigue funcionando, pero resulta más idiomático leer las propiedades correspondientes del objeto:

• $mysqli->connect_error — el mensaje de error (string, o null si tuvo éxito).
• $mysqli->connect_errno — el número del error (un código entero, 0 si tuvo éxito).

El número es útil para ramificar según un fallo específico; el mensaje es para humanos y registros de log.

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

Para un desglose completo del código numérico, consulta mysqli_connect_errno().

Recomendado: hacer que MySQLi lance excepciones

Verificar manualmente el valor de retorno después de cada conexión es fácil de olvidar. Desde PHP 8.1, MySQLi lanza una mysqli_sql_exception en caso de fallo por defecto, lo que te permite gestionar los errores con un bloque try/catch normal. Este es el patrón recomendado para código nuevo:

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

Con el modo de excepciones activado, connect_error rara vez se lee directamente — el mensaje viaja dentro de la excepción en su lugar.

Errores comunes

• No lo llames sobre el objeto de conexión que no pudiste obtener. En una conexión procedural fallida, $mysqli es false, por lo que $mysqli->connect_error daría un error. Usa el mysqli_connect_error() independiente (sin argumento) en ese caso.
• Refleja el último intento. Si abres varias conexiones, el valor pertenece a la llamada de conexión más reciente, no a un manejador específico.
• Nunca muestres errores sin procesar a los usuarios finales en producción. Los mensajes de conexión pueden filtrar nombres de host y nombres de usuario — regístralos y muestra un mensaje genérico en su lugar.

Conclusión

mysqli_connect_error() es una herramienta de depuración pequeña pero esencial: te dice exactamente por qué falló una conexión MySQLi. Combínala con mysqli_connect_errno() cuando necesites el código numérico, prefiere las propiedades OO connect_error/connect_errno cuando te conectas con new mysqli(), y para proyectos nuevos opta por el manejo de errores basado en excepciones. Para aprender más sobre cómo abrir conexiones, consulta mysqli_connect() y la descripción general de MySQLi.

Práctica