If you have ever seen Access denied for user 'root'@'localhost' followed by FATAL ERROR: Upgrade failed during a Zimbra upgrade, you know how frustrating it is. The upgrade process halts, and you are left with a partially updated system. This guide covers what causes this MySQL/MariaDB access error in Zimbra, how to fix it, and how to handle the most common upgrade failures.
What Causes the Error
Zimbra bundles its own MySQL (or MariaDB, depending on the version) instance. During an upgrade, the installer runs database schema migrations that require root-level MySQL access. The “Access Denied” error occurs when:
- The MySQL root password stored by Zimbra no longer matches – Someone manually changed the MySQL root password, or a previous failed upgrade left the password in an inconsistent state.
- MySQL socket file is missing or incorrect – Zimbra’s MySQL uses a specific socket path. If the socket is not where Zimbra expects it, authentication fails.
- Permissions on Zimbra’s MySQL data directory changed – File ownership issues on
/opt/zimbra/db/dataprevent MySQL from starting correctly, which causes authentication failures during the upgrade. - A previous upgrade was interrupted – A partial upgrade can leave MySQL in a state where the grant tables are inconsistent.
Step 1 – Identify the Exact Error
Check the Zimbra upgrade log for the full error message:
cat /tmp/zmsetup.logLook for lines containing “Access denied” or “FATAL ERROR”. A typical error looks like:
ERROR: Access denied for user 'root'@'localhost' (using password: YES)
FATAL ERROR: Upgrade failed - exitingAlso check the Zimbra MySQL error log:
cat /opt/zimbra/log/mysql_error.log | tail -50Step 2 – Retrieve Zimbra’s MySQL Password
Zimbra stores its internal MySQL root password in its local configuration. Switch to the zimbra user and retrieve it:
su - zimbra
zmlocalconfig -s mysql_root_passwordNote down this password. Also check the regular Zimbra MySQL password:
zmlocalconfig -s zimbra_mysql_passwordTry connecting to MySQL manually using the retrieved password:
/opt/zimbra/bin/mysql -u root -pPaste the password from the mysql_root_password output. If this works, the password itself is correct and the issue may be elsewhere. If access is denied, proceed to the next step.
Step 3 – Reset the MySQL Root Password
First, stop all Zimbra services:
su - zimbra -c "zmcontrol stop"Verify everything is stopped:
su - zimbra -c "zmcontrol status"Start MySQL in safe mode, skipping the grant tables (this allows login without a password):
su - zimbra -c "/opt/zimbra/libexec/zminiutil --backup=.pre-fix --section=mysqld --key=skip-grant-tables --set /opt/zimbra/conf/my.cnf"
su - zimbra -c "/opt/zimbra/bin/mysql.server start"Connect to MySQL without a password and reset the root password. Replace NEW_PASSWORD with the password from zmlocalconfig -s mysql_root_password:
su - zimbra -c "/opt/zimbra/bin/mysql -u root"Inside the MySQL shell, run:
FLUSH PRIVILEGES;
ALTER USER 'root'@'localhost' IDENTIFIED BY 'NEW_PASSWORD';
FLUSH PRIVILEGES;
EXIT;Stop MySQL and remove the skip-grant-tables override:
su - zimbra -c "/opt/zimbra/bin/mysql.server stop"
su - zimbra -c "/opt/zimbra/libexec/zminiutil --backup=.post-fix --section=mysqld --key=skip-grant-tables --unset /opt/zimbra/conf/my.cnf"Step 4 – Fix File Permissions
Incorrect ownership on Zimbra directories is a common secondary cause. Fix the permissions:
chown -R zimbra:zimbra /opt/zimbra/db
chown -R zimbra:zimbra /opt/zimbra/data/ldapRun Zimbra’s built-in permission fix script:
/opt/zimbra/libexec/zmfixpermsVerify the ownership on the MySQL data directory:
ls -la /opt/zimbra/db/data/All files should be owned by zimbra:zimbra.
Step 5 – Restart Zimbra and Verify
Start all Zimbra services:
su - zimbra -c "zmcontrol start"Check that all services are running:
su - zimbra -c "zmcontrol status"Confirm MySQL is accessible with the correct password:
su - zimbra -c "/opt/zimbra/bin/mysql -u root -p"Step 6 – Re-run the Upgrade
With MySQL access restored, re-run the Zimbra upgrade installer:
cd /path/to/zimbra-installer
./install.shMonitor the upgrade log in a separate terminal:
tail -f /tmp/zmsetup.logOther Common Zimbra Upgrade Errors
“zmcontrol is not running” during upgrade – The upgrade expects certain services to be running. Start them manually with su - zimbra -c "zmcontrol start" before re-running the installer.
“LDAP replication error” – If you run a multi-server Zimbra environment, make sure the LDAP master is upgraded first. LDAP replication issues block upgrades on replica nodes.
“Disk space insufficient” – The upgrade needs temporary space for database migrations. Ensure at least 5 GB free in /opt/zimbra and /tmp. Check with df -h /opt/zimbra /tmp.
“Service slapd is not running” – Zimbra’s LDAP (slapd) must be running during the upgrade. Start it with su - zimbra -c "ldap start".
“MySQL InnoDB redo log mismatch” – If MySQL crashes during an upgrade, the InnoDB redo logs may be in an inconsistent state. Remove the redo logs and let MySQL recreate them on next start (back up the data directory first):
su - zimbra -c "/opt/zimbra/bin/mysql.server stop"
mv /opt/zimbra/db/data/ib_logfile0 /opt/zimbra/db/data/ib_logfile0.bak
mv /opt/zimbra/db/data/ib_logfile1 /opt/zimbra/db/data/ib_logfile1.bak
su - zimbra -c "/opt/zimbra/bin/mysql.server start"Preventing Future Issues
- Always take a full backup of
/opt/zimbrabefore upgrading. - Never manually modify Zimbra’s MySQL root password through MySQL directly. Use
zmlocalconfigto manage Zimbra passwords. - Run
/opt/zimbra/libexec/zmfixpermsafter any manual file operations in the Zimbra directory tree. - Test upgrades on a staging server before applying to production.
Wrapping Up
The “Access Denied” fatal error during Zimbra upgrades is almost always a MySQL root password mismatch. Retrieve the expected password from zmlocalconfig, reset it in MySQL if needed, fix directory permissions, and re-run the upgrade. Keeping regular backups and testing upgrades in a staging environment will save you from most of these headaches.
