MariaDB Won't Start After a Frappe Install: unknown variable 'innodb-file-format=barracuda'

You followed the ERPNext install guide to the letter. You pasted the recommended [mysqld] block into /etc/mysql/my.cnf, restarted the database, and now the entire MariaDB service is down. Not slow, not degraded: down. Every app on that box that touches the database is now throwing connection errors, and ERPNext is the least of your problems.

The maddening part is that the config you pasted came from an official-looking source. It is not a typo you made. It is a line that used to be correct and is now a fatal error, and nobody updated the guide. The line is innodb-file-format=barracuda, and on MariaDB 10.3.1 or newer it does not warn you. It refuses to start the server at all.

sudo sed -i '/innodb.file.format/d;/innodb.large.prefix/d' /etc/mysql/my.cnf
sudo systemctl restart mariadb

The exact error: unknown variable 'innodb-file-format=barracuda'

Depending on how you started the service, the message lands in one of three places: the terminal, journalctl -u mariadb, or the MariaDB error log at /var/log/mysql/error.log. It reads:

mysqld: unknown variable 'innodb-file-format=barracuda'

You may also see it for the sibling variables, because most guides set all of them together:

mysqld: unknown variable 'innodb-file-format-max=barracuda'
mysqld: unknown variable 'innodb-large-prefix=1'

And from systemd, the unhelpful summary that sends people down the wrong path:

Job for mariadb.service failed because the control process exited with error code.
See "systemctl status mariadb.service" and "journalctl -xe" for details.

That systemd line tells you the process died but not why. The real cause is in the error log, one screen up. This is a good moment to get comfortable reading Linux logs properly rather than guessing.

Why this happens: a config that aged out from under you

MariaDB inherited innodb_file_format from MySQL. It selected the on-disk format for new InnoDB tables: the old Antelope format or the newer Barracuda format, the latter needed for dynamic and compressed row formats and for long index prefixes. For years the standard advice, including Frappe's own older install documentation, was to set it explicitly to Barracuda so that ERPNext's wide indexes on tables like tabGL Entry would work.

Then two things happened. From MariaDB 10.2.2, Barracuda became the default and the only format the server cares about, making the variable redundant. From MariaDB 10.3.1, the variable was removed entirely, along with innodb_file_format_max, innodb_file_format_check and innodb_large_prefix. There is a small twist worth knowing: MariaDB 10.4.3 quietly restored these names as deprecated, ignored placeholders purely so that old configs would not crash. That is why a colleague on 10.4 or 10.5 can run the same my.cnf without a problem while your 10.3.x box falls over. If you are on a 10.3 point release below 10.4.3, the variable is simply unknown.

And an unknown variable is not a warning in MariaDB. By default mysqld treats an unrecognised option as a fatal error and exits during startup. That is deliberate: the server would rather refuse to run than silently ignore a setting an operator clearly intended. The side effect is that one stale line takes down the whole database.

The fix, step by step

Step 1: Confirm the version so you fix the right problem

mysqld --version
# or, on newer packages:
mariadbd --version

Expect something like mysqld Ver 10.5.23-MariaDB. If the number is 10.3.1 or higher, the removed variable is your cause and the rest of this applies. If it is 10.2.x or lower, your problem is something else and you should not delete these lines.

Step 2: Find every file that sets the dead variables

MariaDB reads a whole directory of config, not just my.cnf. Search all of it:

grep -rE 'innodb.file.format|innodb.large.prefix' /etc/mysql/

On a Frappe box the offending block usually lives in /etc/mysql/my.cnf or a file under /etc/mysql/mariadb.conf.d/. The grep prints the file path and the exact lines, so you know precisely what to remove.

Step 3: Delete the removed variables

Edit the file the grep pointed at and remove these lines wherever they appear:

# DELETE all of these on MariaDB 10.3.1 and later
innodb-file-format=barracuda
innodb-file-format-max=barracuda
innodb-file-format-check=ON
innodb-large-prefix=1

Do not comment them with # and leave a note to yourself. A stray uncommented copy in another file will still crash the server. Remove them outright. What you are left with, for a typical ERPNext install on modern MariaDB, is a clean and correct block:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb_file_per_table = 1

[mysql]
default-character-set = utf8mb4

The only line ERPNext genuinely still needs from the old advice is innodb_file_per_table, and even that is on by default. The character set lines are the ones that actually matter for Frappe, because ERPNext requires utf8mb4.

Step 4: Restart and watch it come back

sudo systemctl restart mariadb
sudo systemctl status mariadb --no-pager

You want Active: active (running). If it flaps back to failed, re-run the grep from step 2. There is almost always a second copy of the variable in a file you did not expect.

Verification: prove the database is actually healthy

A running process is not the same as a working database. Confirm you can connect and that the server settled on Barracuda by itself:

sudo mysql -e "SELECT VERSION();"
sudo mysql -e "SHOW VARIABLES LIKE 'innodb_default_row_format';"

Expect the version string and innodb_default_row_format = dynamic, which is a Barracuda-only row format. That is the proof you never needed the explicit setting. Then check that Frappe is happy:

cd ~/frappe-bench
bench --site your-site.local mariadb -e "SELECT COUNT(*) FROM tabUser;"

A row count back means the credentials, the socket and the database are all working again.

What people get wrong

"Just downgrade MariaDB to 10.2 so the guide works." This is the worst advice in these threads. You do not roll a database engine backwards to satisfy a stale config line, and downgrading MariaDB across a major version is not supported and can leave your data files unreadable by the older server. Delete four lines instead.

Commenting the lines out instead of deleting them. People leave a commented copy as a reminder, then paste the block into a fresh server months later and reintroduce the crash. There is nothing to remember here. The setting is gone from MariaDB forever. Delete it.

Setting innodb_strict_mode=0 to "make it tolerant." That is a different variable that changes how strict InnoDB is about row formats at table creation time. It does nothing about an unknown startup variable, and turning it off masks real schema problems later. It is cargo-culted in from unrelated ERPNext threads.

When it is still broken

If MariaDB still will not start after removing the variables, work through these in order:

• Read the actual error log, not the systemd summary. Run sudo tail -n 40 /var/log/mysql/error.log. If the message names a different unknown variable, delete that one too. If it mentions Table 'mysql.user' doesn't exist or InnoDB: Database page corruption, you have a separate and more serious problem.
• Check for a second config directory. Some installs also read /etc/my.cnf or ~/.my.cnf. Widen the grep: grep -rE 'innodb.file.format' /etc/my.cnf /etc/mysql/ 2>/dev/null.
• Look for a disk or permissions issue. A full disk or a datadir owned by the wrong user produces a failed start that looks unrelated. df -h and ls -ld /var/lib/mysql rule those out quickly.
• Validate the config in isolation. Run mysqld --help --verbose 2>&1 | head as the mysql user. If it prints a fatal line, that is the exact remaining problem, stated plainly.

Once the database is back up, this is a good time to make sure you can actually recover it if a config change ever does real damage. Reading the difference between a dump and a tested restore in binlogs and point-in-time recovery for ERPNext is time well spent before the next incident, not after it.