MySQL Internals Manual  /  Error Messages  /  Adding New Error Messages to MySQL

27.1 Adding New Error Messages to MySQL

The procedure for adding error messages depends on which version of MySQL you are using:

  • Before MySQL 5.0.3, error messages are stored in errmsg.txt files in the language directories under sql/share. That is, the files have names like czech/errmsg.txt, danish/errmsg.txt, and so forth, and each one is language-specific. Each of these language-specific files must contain a line for each error message, so adding a new message involves adding a line to the errmsg.txt file for every language. The procedure involves adding the English message to the english/errmsg.txt file and running a script that adds the message to the other language-specific files. Translators may translate the message in other errmsg.txt files later.

  • Beginning with MySQL 5.0.3, error messages are stored in a single errmsg.txt file in the sql/share directory, and it contains the error messages for all languages. The messages are grouped by error symbol. For each symbol, there must be an English message, and messages can be present for other languages as well. If there is no message for a given language, the English version is used. Messages for a given language are written in the character set used for that language, so the file contains information in several character sets.

  • From MySQL 5.5 on, error messages are stored in a single errmsg-utf8.txt file in the sql/share directory. The file format is similar to errmsg.txt, but the contents of the file are written in a single character set, utf8. An added feature is that error messages may contain positional arguments.

The comp_err program compiles the text error message file or files into language-specific errmsg.sys files that each are located in the appropriate language directory under sql/share:

  • Before MySQL 5.5, comp_err reads errmsg.txt and writes errmsg.sys files, each in the character set associated with the language for the file. For example, sql/share/korean/errmsg.sys is written using euckr.

  • From MySQL 5.5 on, comp_err reads errmsg-utf8.txt and writes errmsg.sys files using utf8.

comp_err also generates a number of header files in the include directory. The MySQL build process runs comp_err automatically.

Note: You should observe some general considerations regarding error messages that apply no matter your version of MySQL:

  • Always use parameter constructs such as "%.64s" to guard against buffer overflows. The maximum error message length is MYSQL_ERRMSG_SIZE.

  • Never add new parameters (such as¬†%s) to existing error messages. Error messages must always be backward compatible. If a parameter were added, older servers would crash when run with a newer error message file.

    • If you need to add new parameters to an existing error message, you can introduce a new error message but continue to use the old error code. For example, in MySQL 5.1, the handler::print_keydup_error() method is passed a message like ER(ER_DUP_ENTRY_WITH_KEY_NAME), but always uses the ER_DUP_ENTRY error code.