Skip to main content

How to Troubleshoot a Failed MySQL or MariaDB Upgrade

If a MySQL or MariaDB upgrade fails during the update process in WHM, this article provides the steps to identify the cause and resolve the issue. This procedure is intended for Server Administrators and requires root access to the server.

If a MySQL or MariaDB upgrade fails during the update process in WHM, this article provides the steps to identify the cause and resolve the issue. This procedure is intended for Server Administrators and requires root access to the server.

Before you begin

You will need:

  • Root access to the server via WHM or SSH.

  • A current backup of the database servers before the upgrade was attempted.

  • Access to the server's error logs.

Check the MySQL or MariaDB error logs

The first step in troubleshooting a failed upgrade is identifying the specific error message generated by the database engine.

  1. Access the server via SSH or the WHM Terminal.

  2. Locate the error log. The path typically depends on the version and distribution, but common locations include:

    • /var/log/mysql/error.log

    • /var/log/mariadb/error.log

    • /var/log/messages (or /var/log/syslog on Debian/Ubuntu systems)

  3. Use a command such as tail -n 100 /var/log/mysql/error.log to view the most recent entries.

  4. Look for lines containing [ERROR] or [Fatal] to identify the specific reason the service failed to start or complete the upgrade.

Check service status and port availability

If the service is not running, verify that the system recognizes the service and that the port is not being blocked.

  1. Run the command systemctl status mysql or systemctl status mariadb to see the current status.

  2. If the service is "failed," check the output for specific exit codes.

  3. Verify that the port (typically 3306) is listening by running: netstat -tulpn | grep :3306

  4. If the port is not listening, the service may have failed to start due to a configuration error or a port conflict.

Verify configuration file syntax

A syntax error in the configuration file will prevent the MySQL or MariaDB service from starting after an upgrade.

  1. Identify your primary configuration file (e.g., /etc/my.cnf or /etc/mysql/my.cnf).

  2. Run the check command: mysql_upgrade_check (if available) or manually inspect the file for syntax errors.

  3. Ensure that there are no conflicting directives from previous versions still present in the configuration.

Check for disk space and memory exhaustion

Upgrades often fail if the system runs out of resources during the process of moving or re-indexing data.

  1. Check available disk space: df -h

  2. Check available memory: free -m

  3. If the partition containing /var/lib/mysql or /var/lib/mysql is at 100% capacity, the upgrade will fail.

How to resolve common upgrade failures

Depending on the error found in the logs, perform the following actions:

If the error is a "Table is marked as crashed" or "InnoDB" error:

  1. Run the repair tool: mysqlcheck -u root -p --all-databases --repair.

  2. If InnoDB tables are corrupted, you may need to start the server with innodb_force_recovery enabled in the configuration file.

If the error is a "Permission denied" error:

  1. Ensure the directory permissions are correct: chown -R mysql:mysql /var/lib/mysql

  2. Ensure the permissions are set to 755 or 750 as required by your specific OS.

Contact Hostek support

If you cannot identify the cause of the failure from the logs or if the database remains inaccessible after attempting the steps above, contact Hostek support.

When contacting support, please provide the following information:

  • The specific error message from the /var/log/mysql/error.log or /var/log/mariadb/error.log.

  • The output of systemctl status mysql or systemctl status mariadb.

  • The current version of MySQL or MariaDB you were attempting to upgrade to.

Did this answer your question?