Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

phpMyAdmin says the connection for controluser failed

ErrorConnection for controluser as defined in your configuration failed.

Short answer

phpMyAdmin opens a second connection with controluser and controlpass from config.inc.php to reach its configuration storage. The warning means that login was refused: the account does not exist, its password differs from controlpass, or the MySQL account uses an authentication method the PHP build cannot speak.

  • Applies to phpMyAdmin 5.2, MySQL 8.x, MariaDB 10.x, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open config.inc.php and read the controluser and controlpass lines, then try exactly those credentials in the mysql client.

    grep -n "controluser\|controlpass" config.inc.php
    mysql -u pma -p -e "SELECT CURRENT_USER();"
  2. 2Match what you see, then jump to its fix

    1. 1The mysql client answers Access denied for the user from controluser, or the user is missingThe control user does not exist or the password differsFix
    2. 2controluser and controlpass are set, but you never created the pma databaseYou do not use the configuration storage at allFix
    3. 3The server requested authentication method unknown to the client [caching_sha2_password]The account uses caching_sha2_password but PHP is too oldFix

What does the error look like?

  • Connection for controluser as defined in your configuration failed.
  • mysqli_real_connect(): The server requested authentication method unknown to the client [caching_sha2_password]

Cause 1 of 3

The control user does not exist or the password differs

1Check

controluser and controlpass must match a real MySQL account. If they were set by an installer or copied from another machine, the account may not exist here, or its password was changed.

mysql -u root -p -e "SELECT user, host FROM mysql.user WHERE user='pma';"

2Fix

Create the account with the statements from the phpMyAdmin setup guide (MySQL 8.0 and newer shown), give it rights on the configuration database, and put the same name and password in config.inc.php. Replace pmapass with your own password and <pma_db> with your configuration database.

CREATE USER 'pma'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'pmapass';
GRANT SELECT, INSERT, UPDATE, DELETE ON <pma_db>.* TO 'pma'@'localhost';

// config.inc.php
$cfg['Servers'][$i]['controluser'] = 'pma';
$cfg['Servers'][$i]['controlpass'] = 'pmapass';

3Verify

Reload phpMyAdmin and confirm the warning is gone.

mysql -u pma -ppmapass -e "SELECT 1;"

Confirmed by docs.phpmyadmin.net

Did this fix it?

Cause 2 of 3

You do not use the configuration storage at all

1Check

The control user is only needed to reach the configuration storage. The manual says a single-user setup does not need it.

grep -n "pmadb\|controluser" config.inc.php

2Fix

If you do not want linked-table features, remove the controluser and controlpass lines, or leave them empty. If you want those features, create the account as in the first cause.

// config.inc.php: remove or empty these when unused
// $cfg['Servers'][$i]['controluser'] = '';
// $cfg['Servers'][$i]['controlpass'] = '';

3Verify

Reload the page and confirm the warning no longer appears.

grep -n "controluser" config.inc.php

Confirmed by docs.phpmyadmin.net

Did this fix it?

Cause 3 of 3

The account uses caching_sha2_password but PHP is too old

1Check

MySQL 8 made caching_sha2_password the default for new accounts, and PHP can only use it from version 7.4. Check the PHP version your web server runs.

php -v

2Fix

Upgrade PHP. If you cannot yet, switch the MySQL account to the older method (shown here for the pma account; use your own password).

ALTER USER 'pma'@'localhost' IDENTIFIED WITH mysql_native_password BY 'pmapass';

3Verify

Reload phpMyAdmin and confirm the control connection works.

mysql -u pma -ppmapass -e "SELECT 1;"

Confirmed by docs.phpmyadmin.net

Did this fix it?

How do I stop it coming back?

  • Change the MySQL password and the controlpass line in the same step.
  • Keep config.inc.php out of version control and set its permissions as the FAQ advises.
  • Use a separate pma account with rights only on the configuration database, not root.

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.