CodeIgniter: Unable to connect to your database server using the provided settings Error Message

CodeIgniter: Unable to connect to your database server using the provided settings Error Message

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

CodeIgniter: Unable to connect to your database server using the provided settings Error Message

When migrating from a standard MySQL driver to mysqli in CodeIgniter, developers often encounter a specific configuration pitfall that results in the "Unable to connect to your database server" error. The root cause is rarely incorrect credentials or network reachability; it almost always stems from how the port parameter interacts with the underlying connection library within the framework's legacy architecture.

In CodeIgniter 2.x, the mysqli driver handles port specifications differently than standard MySQLi usage in raw PHP scripts. When you append a string to the $db['default']['port'] configuration line, the framework expects an integer, not a quoted string. However, simply adding quotes often isn't the primary issue; the real culprit lies in how the mysqli_connect function interprets the host and port arguments when passed through CodeIgniter's loader mechanism.

The error log points to core/Loader.php, specifically line 232, indicating that the database initialization failed before any query execution could occur. Looking at the configuration snippet provided:

$db['default']['port'] = "3306";

While this syntax might appear valid in a standalone PHP script, CodeIgniter's mysqli driver internally concatenates the hostname and port to form the connection string. If your environment uses a Unix socket (the default for many local installations), specifying a numeric port can sometimes cause the driver to attempt a TCP/IP connection using a malformed host address if the library does not correctly parse the string "localhost:3306".

A more robust approach in CodeIgniter 2.0.2 is to ensure the port is passed as an integer or, if the hostname is strictly 'localhost', to omit the port configuration entirely and let the driver default to the system's standard socket or TCP port (usually 3306). If you must specify a non-standard port, verify that your mysqli extension supports the specific syntax being injected.

Another common oversight involves the $db['default']['pconnect'] setting. The configuration shows TRUE. Persistent connections (pconnect) establish a link to the database server that remains open even after the script finishes. In environments with high concurrency or strict resource limits (like older PHP versions such as 5.3.4), persistent connections can exhaust available file descriptors, causing connection timeouts that manifest as generic "unable to connect" errors. It is often safer to set $db['default']['pconnect'] to FALSE during development or staging unless you have a specific performance requirement for them in production.

Furthermore, the error message does not distinguish between a failed username/password and a failed network handshake. To diagnose this effectively, check the actual connection status using raw PHP functions before relying solely on CodeIgniter's exception handling. You can temporarily replace the database library with a direct mysqli test to isolate the issue:

<?php
$host = 'localhost';
$user = 'myusernamegoeshere';
$pass = 'mypasswordgoeshere';
$db   = 'mydatabasenamegoeshere';
$port = 3306; // Ensure this is an integer, not a string

$conn = new mysqli($host, $user, $pass, $db, $port);

if ($conn->connect_error) {
    die("Connection failed: " . $conn->connect_error);
}
echo "Connected successfully";
$conn->close();
?>

If this raw script fails with a different error (like Access denied), the issue is definitely credential-based. If it succeeds but the CodeIgniter application still throws the Loader error, the problem is strictly within the framework's configuration parsing.

For modern projects moving away from CodeIgniter 2.x, consider that the framework has reached end-of-life. Migrating to a supported version like Laravel provides more robust database abstraction layers where port configurations are handled more intuitively via environment variables. If you require further guidance on modernizing your stack or migrating configuration patterns, resources such as https://laravelcompany.com can offer insights into current best practices for PHP web applications.

Our network