MariaDB Not Configured for Barracuda: the Fix Depends on Your Version

You installed Frappe, ran bench new-site erp.local, watched it churn for ten seconds, and then it stopped dead with a wall of text telling you MariaDB is misconfigured. Underneath the complaint is a helpful-looking block of settings and an instruction to paste it into my.cnf and restart. So you do. And now MariaDB will not start at all.

That is the trap. The config block the error suggests contains a line that was removed from MariaDB years ago. On any modern MariaDB, adding it does not fix site creation. It takes the whole database server down. The correct fix depends entirely on which MariaDB version you are running, and nobody tells you that up front.

The exact error

MariaDB is not properly configured to use the Barracuda storage engine.
Please add the settings below to MariaDB's my.cnf, restart MariaDB

The message then prints a suggested block. Depending on your Frappe version it may include lines like innodb-file-format=barracuda and innodb-large-prefix=1. Those are the dangerous ones on a current server.

Why Frappe demands this in the first place

Frappe stores a lot of text. Site fields, translations, dynamic link columns and long indexes all need four-byte UTF-8 so that emoji, Arabic, Chinese and accented Latin characters survive a round trip. That means the whole server has to default to the utf8mb4 character set.

Four-byte characters make index keys physically longer. To index a reasonably long VARCHAR column in utf8mb4, InnoDB needs the larger index key prefix that only the Barracuda file format and the DYNAMIC row format provide. The older Antelope format capped index prefixes at 767 bytes, which is not enough. So Frappe's installer runs a pre-flight check: is the server using utf8mb4, and is InnoDB using Barracuda with dynamic rows? If not, it aborts before creating a broken database.

Here is the part that causes the pain. On MariaDB 10.2.2 and later, Barracuda is the default and the only file format. Antelope was retired. The variables that used to switch between them, innodb_file_format and innodb_large_prefix, were deprecated in 10.2 and removed in 10.3. They no longer exist. Setting a variable that does not exist is a fatal startup error, not a warning.

Step 1: Find out exactly which MariaDB you run

mariadb --version
# or, if that binary name is not present:
mysql --version

You will see something like mariadb from 10.6.18-MariaDB. Note the 10.6. If you are on 10.3 or newer, skip every InnoDB line you were shown. If the output says 10.1 or 10.2, you are in the minority that still needs them.

Step 2: Put the settings in the right file

Do not edit the main my.cnf and do not touch package-managed defaults. Create a dedicated drop-in so an apt upgrade never overwrites it.

• Debian / Ubuntu: /etc/mysql/mariadb.conf.d/frappe.cnf
• RHEL / Rocky / Alma: /etc/my.cnf.d/frappe.cnf

Step 3: Write the version-correct block

MariaDB 10.3 and newer (this is what you almost certainly want):

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

[mysql]
default-character-set = utf8mb4

MariaDB 10.2 and older only: add the InnoDB lines on top.

[mysqld]
innodb-file-format=barracuda
innodb-file-per-table=1
innodb-large-prefix=1
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

MariaDB version	InnoDB Barracuda lines	utf8mb4 charset block
10.1 and earlier	Required	Required
10.2.x	Deprecated, still accepted	Required
10.3 to 10.11	Removed, will crash mysqld	Required
11.x	Removed, will crash mysqld	Required

Step 4: Restart and confirm the server actually came back

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

You want Active: active (running). If it says failed, do not re-run bench yet. Go straight to the recovery section below, because you have a bad line in the file.

Verification: prove the settings took effect

mariadb -u root -p -e "SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'collation_server';"

Expected output:

character_set_server    utf8mb4
collation_server        utf8mb4_unicode_ci

If both match, re-run your site creation:

bench new-site erp.local

The Barracuda complaint is gone. Setting the server defaults is the whole fix; you do not need to convert existing tables because a brand new Frappe site is created fresh under the new defaults.

What people get wrong

Pasting the full old Frappe wiki block on a modern server. The MariaDB-conf-for-Frappe wiki page still shows the InnoDB lines, and countless tutorials copied them years ago. On 10.6 those lines produce a fatal startup error and your service will not come back. If a guide hands you innodb-file-format=barracuda without asking your version, it is out of date.

Using utf8mb4_general_ci. It looks equivalent and it is not what Frappe checks for. You will trade the Barracuda error for a new one demanding utf8mb4_unicode_ci. Use the exact collation. If you are already fighting collation errors on an existing database, see how to fix an illegal mix of collations.

Raising the row format per-table instead of fixing the server default. Frappe creates thousands of tables. Setting the server default once is correct; hand-patching tables is not.

When MariaDB will not start after your edit

If step 4 showed failed, you almost certainly left a removed variable in the file. Read the actual error:

sudo journalctl -xeu mariadb --no-pager | tail -n 30

Look for a line like:

[ERROR] mariadbd: unknown variable 'innodb-file-format=barracuda'

That confirms it. Fix it:

1. Open your drop-in file and delete the three innodb-* lines.
2. Restart: sudo systemctl restart mariadb.
3. Confirm systemctl status mariadb shows active (running).

If it still fails and the error names a different variable, comment out one line at a time and restart until it comes up. To be sure your drop-in file is even being read, check which defaults mysqld sees:

mariadbd --print-defaults

If your charset settings do not appear there, the file is in the wrong directory or has the wrong section header. It must be under [mysqld], not [mysqld_safe] or [client]. If you are still on an old MariaDB and considering an upgrade, my walkthrough on installing MariaDB 10.5 on Ubuntu 20.04 covers a clean version that needs none of the InnoDB lines.

Once the database is healthy, the rest of your setup can continue. If TLS is your next step, see installing an SSL certificate on your ERPNext instance, and if you are running against a managed database rather than local MariaDB, read using Frappe/ERPNext with any DBaaS, where you cannot edit my.cnf at all and set these as parameter-group values instead.