CodeIgniter cannot connect to the MySQL database server
Unable to connect to your database server using the provided settings.Short answer
CodeIgniter only reports that its connection failed. Test the same host, port, user and password in a plain mysqli call first: its error number names the cause. It is usually a wrong password (1045), a missing database (1049), a port that localhost ignores, or a wrong driver name.
Fix it fast
1Find out which cause you have
Take the values from your CodeIgniter config and open the connection with plain mysqli, with exceptions switched on. The error text is the real reason.
<?php mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); try { new mysqli('127.0.0.1', 'my_user', 'my_password', 'my_db', 3306); echo 'connected'; } catch (mysqli_sql_exception $e) { echo $e->getCode() . ': ' . $e->getMessage(); }2Match what you see, then jump to its fix
- 1
Access denied for user '...'@'...' (using password: YES), error 1045Wrong username or passwordFix - 2
Unknown database 'my_db', error 1049The database named in the config does not existFix - 3
Can't connect to local MySQL server through socket '...' (2002), or the server on port 3307 is never reachedA port is set but hostname is localhostFix - 4
The mysqli test connects but CodeIgniter still fails right awayThe driver name is wrong for the framework versionFix
- 1
What does the error look like?
Unable to connect to your database server using the provided settings.
Cause 1 of 4
Wrong username or password
1Check
CodeIgniter 3 reads username and password from application/config/database.php. CodeIgniter 4 reads app/Config/Database.php, and values in the .env file override it. A stale .env value is a common surprise.
grep -n "username\|password" application/config/database.php
grep -n "database.default" .env2Fix
Set the same credentials your mysqli test accepted, in the file the framework really uses.
# CodeIgniter 4 .env
database.default.username = 'my_user'
database.default.password = 'my_password'3Verify
Reload the page that failed.
curl -I http://localhost:8080/Confirmed by dev.mysql.com
Cause 2 of 4
The database named in the config does not exist
1Check
The login can be right while the database name is wrong or not created on this server. CodeIgniter 4 ships with the placeholder database_name.
mysql -u my_user -p -e "SHOW DATABASES;"2Fix
Create the database, or set the name in the config to one that exists.
// CodeIgniter 3: application/config/database.php
'database' => 'my_db',
// CodeIgniter 4: app/Config/Database.php or .env
database.default.database = 'my_db'3Verify
Run the mysqli test again and confirm it prints connected.
php test-mysqli.phpConfirmed by dev.mysql.com
Cause 3 of 4
A port is set but hostname is localhost
1Check
With the hostname localhost, mysqli uses a local pipe or Unix socket and the port value is ignored. A MySQL server on a non-default port, as in many local stacks, is then not reached. Error 2003 means the TCP address and port you gave answered nothing.
php -r 'mysqli_report(MYSQLI_REPORT_OFF); $m=@new mysqli("127.0.0.1","my_user","my_password","my_db",3307); echo $m->connect_errno,": ",$m->connect_error;'2Fix
Use 127.0.0.1 as the hostname when you need a specific port, and make sure the port matches the server.
// CodeIgniter 3
'hostname' => '127.0.0.1',
'port' => 3307,
// CodeIgniter 4
database.default.hostname = 127.0.0.1
database.default.port = 33073Verify
Run the mysqli check with the same host and port and confirm it connects.
php test-mysqli.phpConfirmed by php.net
Cause 4 of 4
The driver name is wrong for the framework version
1Check
In CodeIgniter 3 the dbdriver value must be written in lower case, for example mysqli, and the old mysql driver is deprecated. In CodeIgniter 4 the setting is DBDriver and the default is MySQLi.
grep -n "dbdriver\|DBDriver" application/config/database.php app/Config/Database.php 2>/dev/null2Fix
Use mysqli, and add the port line yourself in CodeIgniter 3 if you need a non-default port.
// CodeIgniter 3
'dbdriver' => 'mysqli',
// CodeIgniter 4
'DBDriver' => 'MySQLi',3Verify
Reload the page and confirm the database error is gone.
curl -I http://localhost:8080/Confirmed by codeigniter.com
How do I stop it coming back?
- Keep real credentials in .env (CodeIgniter 4) or per-environment config (CodeIgniter 3), not in the committed default file.
- Keep a one-file mysqli test script for the server so connection problems are tested without the framework.
- Use 127.0.0.1 and an explicit port in every environment.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Back end
CodeIgniter 4: try/catch does not catch a failed insert in the model
DatabaseException
CodeIgniter throws a DatabaseException on a failed query only when DBDebug is true, and inside a transaction it does not throw unless you ask.
3 causes, each with a fixBack end
CodeIgniter 4 where() builds a different condition than you meant
A SQL syntax error that appears only when a value contains a quote character
The query builder joins every where() with AND and every orWhere() with OR, with no brackets.
3 causes, each with a fixBack end
Call to undefined function mysql_pconnect() after a PHP upgrade
Call to undefined function mysql_connect()
The old mysql_* functions belonged to the ext/mysql extension, which PHP removed in version 7.0.
2 causes, each with a fixBack end
Laravel insert fails with 'Field user_id doesn't have a default value'
The insert works when the column is removed or made nullable
Error 1364 means Laravel sent an INSERT without a value for a NOT NULL column that has no default, and MySQL strict mode refuses it.
3 causes, each with a fixBack end
Laravel migration cannot drop a column that has a foreign key
Error on rename of '%s' to '%s' (errno: %d - %s)
MySQL refuses to drop a column while a foreign key constraint still uses it.
2 causes, each with a fixBack end
Laravel: distinct() and count() give the total instead of the unique count
select('city')->distinct()->count() ignores the select
Laravel builds the count from the column you pass to count(), not from select().
2 causes, each with a fix