Emergency server help: get in touch

MariaDB Unknown Variable After Upgrade: Fix Failed Startup

When MariaDB refuses to start after an upgrade with an unknown variable or unknown option error, the cause is a removed setting in my.cnf; this guide shows how to find it quickly, lists the variables removed across recent versions, and covers the related redo-log failure.

Published Updated 9 min read

Update, 9 October 2026: replaced the automated “known options” comparison, which could list valid options as unknown, with my_print_defaults --mysqld and a check against the removed-variables list. Found in an independent review.

Applies to MariaDB 10.6, 10.11, 11.4, 11.8 and 12.x on Linux (cPanel & WHM 136+ offers up to 11.8; DirectAdmin and standalone installs may run 12.x), configured through /etc/my.cnf and /etc/my.cnf.d/*.cnf.

Short answer: A MariaDB unknown variable error at startup means /etc/my.cnf or a file in /etc/my.cnf.d/ still sets an option the new version no longer knows, for example wsrep_strict_ddl, innodb_file_format or, on 12.x, big_tables. Find the exact name in journalctl -u mariadb --no-pager -n 30 or the MariaDB error log, comment that line out, start the service and repeat until it stays up. Then run mariadb-upgrade. Query cache options are still valid in MariaDB and are not the cause. (Reviewed October 2026.)

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.

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).err

Look 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, print every option the server will actually read, after all !include and !includedir files, and check the names against the removed-variables list in the next section. my_print_defaults --mysqld reads the same option groups as the server ([mysqld], [server], [mariadb] and the versioned ones) without starting it, and skips client sections:

pd=$(command -v mariadb-print-defaults || command -v my_print_defaults)
"$pd" --mysqld
"$pd" --mysqld | sed 's/^--//; s/=.*//; s/-/_/g' | grep -xE 'innodb_log_files_in_group|innodb_log_write_ahead_size|wsrep_strict_ddl|big_tables|large_page_size|storage_engine|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|thread_concurrency|innodb_thread_concurrency|innodb_commit_concurrency|innodb_concurrency_tickets|innodb_buffer_pool_instances'

The second command prints the configured names that appear in the removed list (dashes and underscores are treated alike). Not every name it prints fails on your version: big_tables, for example, is still valid on 10.11 and 11.x and only fails on 12.0 and later, so check each one against the list below. It also cannot catch a name that is not on the list, so the startup error stays the authority: start the server, read the error, fix that line, and repeat until it starts.

Earlier versions of this guide compared the configuration with the output of mariadbd --verbose --help. That comparison gave false “unknown” results: the help output’s layout differs between versions and for options with short aliases, and it reads the same broken configuration it is meant to check. We replaced it with the commands above, which we tested on MariaDB 10.11.19 (9 October 2026) with a test configuration: options in an included directory were read, a .bak file was skipped and the client section was ignored.

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_files_in_group: removed in 10.6. innodb_log_write_ahead_size: removed in 10.8 but reintroduced in 10.11.9, 11.4.3 and later releases, so it only fails on older builds of those series. innodb_log_group_home_dir is still a valid option.
  • wsrep_strict_ddl: deprecated in 10.6 and removed by 10.11; replaced by wsrep_mode.
  • keep_files_on_create: deprecated in 10.8 but never removed (the deprecation is reverted in 13.0), so it does not cause this error.
  • big_tables, large_page_size, storage_engine: removed in 12.0, so they stop the upgrade from 11.8 to 12.3; use default_storage_engine instead of storage_engine.
  • query_cache_size, query_cache_type, query_cache_limit: still valid in MariaDB. The query cache is present but disabled by default (query_cache_type=OFF), so these lines do not cause an unknown-variable error on MariaDB.
  • 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: both gone; innodb_thread_concurrency was removed in 10.6, together with innodb_commit_concurrency, innodb_concurrency_tickets and innodb_buffer_pool_instances.

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_mysql

On 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 mariadb

If the variables are clean and the server still exits, read the log for InnoDB lines. InnoDB: Upgrade after a crash is not supported means the old server did not shut down cleanly (it crashed, was killed or used innodb_fast_shutdown=2), so its pre-10.8 format redo log is not empty and 10.8 and later will not replay it. A normal shutdown with the default innodb_fast_shutdown=1 leaves the log clean. InnoDB: Unsupported redo log format means the log was written by a newer release than the one now starting. 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 ending in .cnf in an !includedir directory is parsed, in alphabetical order; files with other extensions such as .bak are skipped, but a copy named old-server.cnf is read. Move stale .cnf copies 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 OK

The 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.

Undo or roll back

  • Before commenting anything out, copy the configuration: cp -a /etc/my.cnf /root/my.cnf.bak and cp -a /etc/my.cnf.d /root/my.cnf.d.bak. Keep the copies outside /etc/my.cnf.d/ so they are not read as option files.
  • To undo a change, restore the copied file (or uncomment the line) and restart MariaDB; this only makes sense for options the installed version still accepts.
  • The package upgrade itself cannot be reversed in place; MariaDB does not support downgrading between major versions, so the rollback is the pre-upgrade dump or a server snapshot.

Official documentation (checked 9 October 2026): InnoDB System Variables · MariaDB Documentation · Server System Variables · MariaDB Documentation · Query Cache · MariaDB Documentation · MariaDB 10.6.0 Release Notes · Upgrading from MariaDB 10.6 to MariaDB 10.11 · MariaDB Documentation · Upgrading from MariaDB 11.8 to MariaDB 12.3 · MariaDB Documentation · Configuring MariaDB with Option Files · MariaDB Documentation · InnoDB Redo Log · MariaDB Documentation · mariadb-upgrade · MariaDB Documentation · Error Log · MariaDB Documentation · Supported MySQL/MariaDB Versions · cPanel & WHM documentation

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 .cnf 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 10.6, 10.11, 11.4, 11.8 and 12.x on Linux (cPanel & WHM 136+ offers up to 11.8; DirectAdmin and standalone installs may run 12.x), configured through /etc/my.cnf and /etc/my.cnf.d/*.cnf.
Last full review
Next review

Share this guide

Free website test

Is your website set up right?

Check SSL, security headers, redirects, robots.txt, sitemap, llms.txt and security.txt in one test. It takes about 30 seconds.