The upgrade finished, the packages are installed, and systemctl start mariadb fails within a second. The error log contains a line about an unknown variable or an unrecognised option, and the service exits before it has opened a single table. This is the single most common post-upgrade failure we see, it is entirely caused by configuration, and it is fixed in a minute once you know where to look. This guide covers the diagnosis, the list of variables removed in recent versions, and the redo-log failure that sometimes hides behind it.
Applies to MariaDB upgrades to 10.8, 11.x and 12.3 on cPanel, DirectAdmin and standalone servers
Table of Contents
Short answer: MariaDB refuses to start because /etc/my.cnf or a file under /etc/my.cnf.d/ still sets a variable the new version removed, such as query_cache_size or innodb_log_write_ahead_size. Read the exact name from the error log, comment that line out, start the service and repeat until it stays up, then run mariadb-upgrade to finish the job.
Read the actual error
Do not guess. The error log names the variable:
systemctl status mariadb --no-pager -l
journalctl -u mariadb --no-pager -n 30
tail -30 /var/lib/mysql/$(hostname).errLook for a line like unknown variable 'innodb_log_write_ahead_size=8192' or unknown option '--query-cache-size'. On cPanel the log path may be /var/lib/mysql/<hostname>.err; on DirectAdmin and standalone servers it can be /var/log/mariadb/mariadb.log or wherever log_error points. If none of those exist, journalctl has it.
The server stops at the first unknown variable it meets, so after fixing one, start again and check for the next; there are often two or three.
Find every candidate in one pass
Rather than fixing them one at a time, list every non-comment line in the configuration and compare against what the new server knows:
grep -hvE '^\s*(#|$|\[)' /etc/my.cnf /etc/my.cnf.d/*.cnf 2>/dev/null | cut -d= -f1 | tr -d ' ' | sort -u > /root/cnf-vars.txt
mariadbd --verbose --help 2>/dev/null | grep -E '^ --' | sed 's/^ --//; s/[ =].*//' | tr '_' '-' | sort -u > /root/known-vars.txt
comm -23 <(tr '_' '-' < /root/cnf-vars.txt) /root/known-vars.txtmariadbd --verbose --help prints every option the installed binary accepts, and the comm command prints the configured names that are not among them. Client-section options such as socket under [client] appear in the list too and are harmless; look at the rest.
Variables removed in recent versions
These are the ones that turn up most often in hosting configurations, with the version that removed them:
innodb_log_write_ahead_size,innodb_log_files_in_group,innodb_log_group_home_dirsemantics changed: removed or ignored from 10.8 with the single redo log.wsrep_strict_ddl: removed in 10.6-era Galera changes; replaced bywsrep_mode.keep_files_on_create: removed in 11.x.big_tables,large_page_size,storage_engine: removed in 12.3.query_cache_size,query_cache_type,query_cache_limit: the query cache was removed entirely; any of these stops 11.x and later.innodb_additional_mem_pool_size,innodb_use_sys_malloc,innodb_file_format,innodb_large_prefix,innodb_checksums,innodb_locks_unsafe_for_binlog,innodb_stats_sample_pages: long-deprecated 5.x-era settings that a decade-old tuning guide told someone to add.thread_concurrency,innodb_thread_concurrency(the latter still exists but is deprecated; the former is gone).
Comment each one out rather than deleting it, with a note of the date and the version, so the next engineer understands why the line is there.
Panel-managed configuration
On cPanel, /etc/my.cnf is written by the panel during upgrades and contains a short managed block; custom settings belong in /etc/my.cnf.d/. If the unknown variable is inside the managed block, remove it anyway and then run:
/scripts/mysqlconnectioncheck
/scripts/restartsrv_mysqlOn DirectAdmin, CustomBuild’s da build mariadb copies a template into place and preserves your file unless you told it not to; the removed variable is almost always something added by hand years ago.
Start the service and run the upgrade step
Once the configuration parses, the server starts and you must run the system-table upgrade, which the panel tool may not have reached because the service never came up:
systemctl start mariadb
mariadb-upgrade
systemctl restart mariadbThe related redo-log failure
If the variables are clean and the server still exits, read the log for InnoDB lines. A message about an unsupported redo log format, or about the log being from a different version, means the previous instance shut down with innodb_fast_shutdown at its default of 1 and left work in the log that the new version cannot replay. The prevention is a slow shutdown before the upgrade, as in our safe WHM upgrade guide.
The cure, if the old packages are still available, is to reinstall them, start, run a slow shutdown, and upgrade again. If they are not, the choices narrow to the vendor recovery procedure or a restore from the pre-upgrade dump, and the MariaDB will not start guide works through that decision.
Common pitfall. Fixing the variable in /etc/my.cnf when the offending copy is in /etc/my.cnf.d/server.cnf or in a file with an unexpected extension that is still included. Check the include directives at the bottom of /etc/my.cnf:
grep -E '^!include' /etc/my.cnf
ls -la /etc/my.cnf.d/Every file in an included directory is parsed, including ones named .bak if the include uses a wildcard; move backups out of the directory.
Verify
systemctl is-active mariadb
mariadb -e "SELECT VERSION(); SHOW GLOBAL STATUS LIKE 'Uptime';"
tail -20 /var/lib/mysql/$(hostname).err | grep -ciE 'unknown|error'
mariadb-check --all-databases --check-upgrade | grep -v OKThe service is active, the version is the new one, the error count in the log tail is zero, and every table checks out. Then compare the settings the server is now running against what you intended, because a removed variable often had a replacement that needs to be set:
mariadb -e "SHOW GLOBAL VARIABLES LIKE 'innodb_log_file_size'; SHOW GLOBAL VARIABLES LIKE 'default_storage_engine';"Record the removed lines in your upgrade notes so the same configuration is not copied to the next server.
MariaDB unknown variable at a glance
Official documentation: MariaDB documentation, Linux man pages.
Related guides: Tuning InnoDB on MariaDB 11/12 for cPanel shared hosting: buffer pool, redo log and I/O · Fix “Too many connections” on MariaDB/MySQL (cPanel) · MariaDB 11.8/12.x vector search: using the VECTOR type and VEC_DISTANCE in PHP applications.
Frequently asked questions
Does the unknown variable error also happen when switching from MySQL to MariaDB?
Yes, and it is more common there because MySQL 8 options such as default_authentication_plugin, caching_sha2_password settings and innodb_dedicated_server mean nothing to MariaDB. The diagnosis is identical: read the name from the error log and comment the line out.
How do I find which my.cnf file contains the removed variable?
Run grep -rn 'variable_name' /etc/my.cnf /etc/my.cnf.d/ and check the !include lines at the bottom of /etc/my.cnf, because every file in an included directory is parsed. Panel-managed blocks and hand-added files under /etc/my.cnf.d/ are the usual hiding places.
Can I put the removed variable back once the server is running?
No. A variable the binary does not know is rejected at every start, so the line must stay commented out. If it had a replacement, such as innodb_log_file_size for the old multi-file redo settings, set the replacement instead and document the change.
Maintenance record
This guide changes servers, data or security settings, so we re-check it against current versions on a fixed schedule. Take a backup or snapshot before you start.
- Maintained by
- srvScripts editorial team
- Supported versions
- MariaDB upgrades to 10.8, 11.x and 12.3 on cPanel, DirectAdmin and standalone servers
- Last full review
- Next review
- Sources
- mariadb.com/docs