Issue/Introduction

This article helps troubleshoot ZSphere upgrade failures that report unknown variable wait_timeout.

Symptoms

• The upgrade fails with an error containing unknown variable 'wait_timeout=600'.
• The user previously modified /etc/my.cnf for database security hardening.

Environment

• Product: ZVF
• Version: 4.x
• Component: ZSphere
• Affected object: upgrade or database
• Scenario: For management plane and upgrade issues, confirm the current version, deployment type, storage type, and operation timeline.

Possible causes

• The location or syntax of added parameters in my.cnf does not meet requirements for the current MariaDB or MySQL version.
• Security-hardening parameters affect database startup or upgrade script connections.
• Dual-management-node configurations are inconsistent, and database configuration was not aligned before the upgrade.

Resolution

Perform the following checks in order, and record the affected object, occurrence time, complete error message, and current status.

1. Before the upgrade, back up the database and configuration files such as /etc/my.cnf.
2. Check the section and syntax of custom parameters such as wait_timeout in my.cnf.
3. Temporarily remove or correct incompatible parameters, verify that the database can start, and then upgrade again.
4. For dual management nodes, verify configuration consistency separately to avoid recurrence after primary-standby switchover.

Remediation

1. According to requirements for the current MariaDB or MySQL version, correct or remove custom parameters in my.cnf whose location or syntax is incompatible.
2. After confirming that the database can start normally and database configuration is consistent on dual management nodes, perform the upgrade again.

Verification

• The database and management service start normally, and logs no longer contain unknown variable 'wait_timeout=600'.
• Upgrade prechecks and the upgrade workflow no longer fail because of this parameter.

Notes

• Do not continue the upgrade immediately after changing only the parameter in the error. Perform subsequent steps only after upgrade prechecks and database startup checks pass.