Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

MySQL error 1115: Unknown character set 'utf8mb4'

ErrorERROR 1115 (42000): Unknown character set: 'utf8mb4'

Short answer

Error 1115 means the server or client library got a character set name it does not know. Run SHOW CHARACTER SET on the server that rejects it. If utf8mb4 is not listed, load the dump into a server that has it, or dump with a character set the target lists. Otherwise check the charsets directory and any client option file.

  • Applies to MySQL 8.0, MySQL 8.4 LTS
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the server that throws the error which character sets it knows. Run this on the target, not on the source.

    SELECT VERSION();
    SHOW CHARACTER SET WHERE Charset LIKE 'utf8%';
  2. 2Match what you see, then jump to its fix

    1. 1SHOW CHARACTER SET returns no utf8mb4 row on the server that fails to load the fileThe target server does not list utf8mb4Fix
    2. 2The message says the set is not a compiled character set and not in Index.xmlThe charset index file or directory is wrongFix
    3. 3The error appears on connect, before any of your SQL runsAn option file forces a charset name the client does not knowFix

What does the error look like?

  • ERROR 1115 (42000): Unknown character set: 'utf8mb4'
  • Character set 'utf8mb4' is not a compiled character set and is not specified in the '/usr/share/mysql/charsets/Index.xml' file

Cause 1 of 3

The target server does not list utf8mb4

1Check

mysqldump writes SET NAMES with utf8mb4 by default, so a dump taken today names utf8mb4, which the target may not have. Look at the top of the dump file.

head -n 40 dump.sql | grep -i "set names"

2Fix

Restore into a server that lists utf8mb4. If the target cannot be upgraded, make the dump again with a character set the target does list.

mysqldump --default-character-set=utf8mb3 mydb > dump.sql
# use a name that SHOW CHARACTER SET on the target actually shows

3Verify

Load the new file and check that tables and data are there.

mysql mydb < dump.sql

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 3

The charset index file or directory is wrong

1Check

A program that looks for character sets in the wrong directory, or an Index.xml that lacks the name, cannot find it. The usual directory is share/mysql/charsets or share/charsets under the installation path.

ls /usr/share/mysql/charsets/ | head

2Fix

Point the program at the right directory with the character-sets-dir option, or replace the index file with one that lists the set.

[client]
character-sets-dir=/usr/local/mysql/share/mysql/charsets

3Verify

Start the client again and run the failing statement.

mysql -e "SET NAMES utf8mb4; SELECT @@character_set_client;"

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 3

An option file forces a charset name the client does not know

1Check

A [client] section with default-character-set makes client programs use that name on every connection.

grep -R -n default-character-set /etc/mysql/ ~/.my.cnf

2Fix

Correct the name, or remove the line so the client uses its default.

[client]
default-character-set=utf8mb4

3Verify

Reconnect and print the connection character set.

mysql -e "SHOW VARIABLES LIKE 'character_set_client';"

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Restore dumps into the same major version or newer than the server that made them.
  • Name the charset in one place, the server option file, and keep client files free of overrides.
  • Check SHOW CHARACTER SET on a new server before the first import.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.