MySQL Forge

Resources for the MySQL Community

Category: MySQLDevelopment

MySQL Internals Error Messages

← Back to MySQL Internals overview page

Contents 1 Error Messages 1.1 Adding New Error Messages to MySQL 1.1.1 Adding an error message in multiple MySQL versions 1.1.2 Specific procedure for current MySQL versions 1.1.3 Specific procedure for old (< MySQL 5.0) versions 1.2 Adding Storage Engine Error Messages

[edit] Error Messages

This chapter describes how error messages are defined and how to add the capability of generating error messages to a table handler.

[edit] Adding New Error Messages to MySQL

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.

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. It 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 constructs such as "%s-.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 backwards 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.

[edit] Adding an error message in multiple MySQL versions

It is critical that error codes are identical in all versions. That is, the value of ER_SOME_ERROR must be the same on all versions for which it is defined. The following procedure follows from this requirement.

Let GA reference the most recent stable version. For example, if MySQL 5.1 is GA, and MySQL 5.2 is -beta, then GA refers to MySQL 5.1.

To add a new error message in multiple versions, first add the specific error message to the GA version, at the end of errmsg.txt.

Next, add the specific error message to all versions > GA, at the same position in errmsg.txt, not at the end of the file. This will ensure that the error code value is the same in GA and all later versions. This will have the side effect that any error codes which are not in GA will change their values in post-GA versions. This is acceptable, in non-stable versions. We consider pre-RC versions non-stable in this context.

Finally, for any version < GA, do not add the specific error message. Instead, use the ER_UNKNOWN_ERROR error code, and print a helpful error text with code similar to this:

 my_printf_error(ER_UNKNOWN_ERROR,
                 "Some error text here, with the '%-.64s' parameter value"
                 MYF(0), a_parameter);

This will provide the user with useful information, while ensuring that all versions have consistent error codes.

[edit] Specific procedure for current MySQL versions

Follow these steps for current MySQL versions. For versions before MySQL 5.0.3, see below.

You need only to edit errmsg.txt, and comp_err generates the header files automatically. The errmsg.txt file begins with some lines that define general characteristics of error messages, followed by sections for particular messages. The following example shows a partial listing of an errmsg.txt file. (The languages line is wrapped here; it must be given all on one line.)

languages czech=cze latin2, danish=dan latin1, dutch=nla latin1,
english=eng latin1, estonian=est latin7, french=fre latin1, german=ger
latin1, greek=greek greek, hungarian=hun latin2, italian=ita latin1,
japanese=jpn ujis, japanese-sjis=jps sjis, korean=kor euckr,
norwegian-ny=norwegian-ny latin1, norwegian=nor latin1, polish=pol
latin2, portuguese=por latin1, romanian=rum latin2, russian=rus
koi8r, serbian=serbian cp1250, slovak=slo latin2, spanish=spa latin1,
swedish=swe latin1, ukrainian=ukr koi8u;

default-language eng

start-error-number 1000

ER_HASHCHK
        eng "hashchk"
ER_NISAMCHK
        eng "isamchk"
ER_NO
        cze "NE"
        dan "NEJ"
        nla "NEE"
        eng "NO"
        est "EI"
        ...

Indentation is significant. Unless otherwise specified, leading whitespace should not be used.

The grammar of the errmsg.txt file looks like this:

languages langspec [, langspec] ... ;

start-error-number number

default-language langcode

error-message-section
error-message-section
...

The languages line lists the languages for which language-specific errmsg.sys files should be generated. A language specification langspec in the languages line has this syntax:

langspec: langname=langcode langcharset

langname is the long language name, langcode is the short language code, and langcharset is the character set to use for error messages in the language.

The default-language line specifies the short language code for the default language. (If there is no translation into a given language for a given error message, the message from the default language will be used.)

The start-error-number line indicates the number to be assigned to the first error message. Messages that follow the first one are numbered consecutively from this value.

Each error-message-section begins with a line that lists an error (or warning) symbol, optionally followed by one or two SQLSTATE values. The error symbol must begin with ER_ for an error or WARN_ for a warning. Lines following the error symbol line provide language-specific error messages that correspond to the error symbol. Each message line consists of a tab, a short language code, a space, and the text of the error message within double quote ('"') characters. Presumably, there must be a message in the default language. There may be message translations for other languages. Order of message lines within a section does not matter. If no translation is given for a given language, the default language message will be used. The following example defines several language translations for the ER_BAD_FIELD_ERROR symbol:

ER_BAD_FIELD_ERROR 42S22 S0022
        dan "Ukendt kolonne '%-.64s' i tabel %s"
        nla "Onbekende kolom '%-.64s' in %s"
        eng "Unknown column '%-.64s' in '%-.64s'"
        est "Tundmatu tulp '%-.64s' '%-.64s'-s"
        fre "Champ '%-.64s' inconnu dans %s"
        ger "Unbekanntes Tabellenfeld '%-.64s' in %-.64s"

In the preceding example, two SQLSTATE values are given following the error symbol (42S22, S0022). Internally (in sql/sql_state.c), these are known as odbc_state and jdbc_state. Currently, only the first appears ever to be used.

Message strings for a given language must be written in the character set indicated for that language in the languages line. For example, the language information for Japanese in that line is japanese=jpn ujis, so messages with a language code of jpn must be written in the ujis character set. You might need to be careful about the editor you use for editing the errmsg.txt file. For example, there is a report that using Emacs will mangle the file, whereas vi will not.

Within a message string, C-style escape sequences are allowed:

\\  \
\"  "
\n  newline
\N  N, where N is an octal number
\X  X, for any other X

A line beginning with a '#' character is taken as a comment. Comments and blank lines are ignored.

Use the following procedure to add new error messages:

1. To add a new language translation for an existing error message, find the section for the appropriate error symbol. Then add a new message line to the section. For example:

Before:

ER_UNKNOWN_COLLATION
        eng "Unknown collation: '%-.64s'"
        ger "Unbekannte Kollation: '%-.64s'"
        por "Collation desconhecida: '%-.64s'"

After (with a new Spanish translation):

ER_UNKNOWN_COLLATION
        eng "Unknown collation: '%-.64s'"
        ger "Unbekannte Kollation: '%-.64s'"
        por "Collation desconhecida: '%-.64s'"
        spa "Collation desconocida: '%-.64s'"

1. To add an entirely new error message, go to the end of the errmsg.txt file. Add a new error symbol line, followed by a message line for the default language, and message lines for any translations that you can supply.
2. Make a full build (configure + make). A make all is insufficient to build the sql/share/*/errmsg.sys files.

comp_err will generate the errmsg.sys files, as well as the header files mysqld_error.h, mysqld_ername.h, and sql_state.h in the include directory.

Be aware that if you make a mistake editing a message text file, comp_err prints a cryptic error message and gives you no other feedback. For example, it does not print the input line number where it found a problem. It's up to you to figure this out and correct the file. Perhaps that is not a serious difficulty: errmsg.txt tends to grow by gradual accretion, so if an error occurs when comp_err processes it, the problem is likely due to whatever change you just made.

[edit] Specific procedure for old (< MySQL 5.0) versions

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.

1. Open the file sql/share/english/errmsg.txt in an editor.
2. Add new error messages at the end of this file. Each message should be on a separate line, and it must be quoted within double quote ('"') characters. By convention, every message line except the last should end with a comma (',') following the second double quote.
3. For each new error message, add a #define line to the include/mysqld_error.h file before the last line (#define ER_ERROR_MESSAGES).
4. Adjust the value of ER_ERROR_MESSAGES to the new number of error messages.
5. Add the defined error symbols to include/sql_state.h. This file contains the SQL states for the error messages. If the new errors don't have SQL states, add a comment instead. Note that this file must be kept sorted according to the value of the error number. That is, although the sql_state.h file might not contain an entry for every symbol in mysqld_error.h, those entries that are present in sql_state.h must appear in the same order as those for the corresponding entries in mysqld_error.h.
6. Go to the sql directory in a terminal window and type ./add_errmsg N. This will copy the last N error messages from share/english.txt to all the other language files in share/.
7. Translate the error message for those languages that you know by editing the files share/language/errmsg.txt.
8. Make a full build (configure + make). A make all is insufficient to build the sql/share/*/errmsg.sys files.

[edit] Adding Storage Engine Error Messages

To add error messages for table handlers, the following example may be helpful.

Purpose: Implement the handler::get_error_message function as ha_federated::get_error_message to return the handler-specific error message.

Example:

1. When an error occurs you return an error code. (It should not be in the range of those that HA_ERR uses, which currently is 120-159.)
2. When handler::print_error is called to convert the handler error code to a MySQL error code, it will enter the default label of the switch(error) statement:

handler.cc:1721
  default:
    {
      /* The error was "unknown" to this function.
     Ask handler if it has got a message for this error */
      bool temporary= FALSE;
      String str;
      temporary= get_error_message(error, &str);
      if (!str.is_empty())
      {
    const char* engine= table_type();
    if (temporary)
      my_error(ER_GET_TEMPORARY_ERRMSG, MYF(0), error, str.ptr(), engine);
    else
      my_error(ER_GET_ERRMSG, MYF(0), error, str.ptr(), engine);
      }
      else
    my_error(ER_GET_ERRNO,errflag,error);
      DBUG_VOID_RETURN;
    }
  }

1. Thus the handler::get_error_message is called and you can return the handler-specific error message, which is either a static error message that you retrieve from an error/string array, or a a dynamic one that you format when the error occurs.

When you have returned the error message it will be passed to MySQL and formatted as Got error %d '%-.100s' from %s. For example:

Got error 788  'Could not connect to remote server fed.bb.pl' from FEDERATED

The Got error %d part will be returned in the user's selected language, but the handler-specific one will use English (unless the handler supports returning the handler error message in the user's selected language).