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
sql/share. That is, the
files have names like
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
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
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
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
Before MySQL 5.5, comp_err
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
From MySQL 5.5 on, comp_err
errmsg-utf8.txt and writes
errmsg.sys files using
comp_err also generates a number
of header files in the
include directory. The
MySQL build process runs comp_err
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
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
method is passed a message like
always uses the
It is critical that error codes are identical in all versions.
That is, the value of ER_SOME_ERROR must be the same in all
versions for which it is defined. The following procedure
follows from this requirement. (The discussion uses the name
errmsg.txt, but when you cross the boundary
from before MySQL 5.5 to 5.5 or higher, you should use
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
Next, add the specific error message to all versions >
GA, at the same
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
Finally, for any version < GA,
do not add the specific error
message. Instead, use the
error code, and print a helpful error text with code similar to
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.
If you need to merge error messages up from 5.1 to 5.5, the
merge operation will update the 5.5
errmsg.txt file with information that then
needs to be added to the
file. To handle this, you can use the
errmsg-cnv.sh script, which
errmsg-utf8.txt. However, you must be careful
not to wipe out the existing 5.5-specific information in
Suppose that you added a new error message into 5.1 and have merged this change into 5.5. You can do the following:
1. Make a backup of
cp errmsg-utf8.txt errmsg-utf8.txt.sav
2. Convert 5.1 messages:
Note: This will add 5.1
errmsg-utf8.txt, but remove 5.5
errmsg-utf8.txt.sav in a text editor, then
cut and paste 5.5-specific messages into
4. Make sure everything went fine:
bzr diff errmsg-utf8.txt
The file you edit to add a new error message depends on your version of MySQL:
MySQL 5.0.3 up to 5.5: Edit
MySQL 5.5 and up: Edit
In either case, comp_err generates the header files automatically during the MySQL build process.
errmsg-utf8.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 the file. (The
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" ...
A line beginning with a '
#' character is
taken as a comment. Comments and blank lines are ignored.
Indentation is significant. Unless otherwise specified, leading whitespace should not be used.
The grammar of the
errmsg.txt file looks like
languages langspec [, langspec] ... ; start-error-number number default-language langcode error-message-section error-message-section ...
languages line lists the languages for
should be generated. A language specification
langspec in the
languages line has this syntax:
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. langcharset
is irrelevant as of MySQL 5.5 because all
errmsg.sys files are written using
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.)
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
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 ('
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 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 (
S0022). Internally (in
sql/sql_state.c), these are known as
Currently, only the first appears ever to be used.
errmsg-utf8.txt, the entire file is
utf8. As long as your editor can
utf8, there should be no problem
editing the file.
errmsg.txt, message strings for
a given language must be written in the character set indicated
for that language in the
line. For example, the language information for
Japanese in that line is
so messages with a language code of
be written in the
ujis character set. You
might need to be careful about the editor you use for editing
errmsg.txt file. For example, there is a
report that using Emacs will
mangle the file, whereas vi
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
In MySQL 5.5 and up, error messages can contain positional constructs for arguments. This is convenient when arguments are most naturally specified in different orders in different languages. Positional arguments enable and error-message writer to avoid awkward language or unnecessarily long messages that result from having the arguments in the same order in all languages.
To specify a positional argument, include a single digit 0
to 9 and a dollar sign in the formatting specifier for each
argument in the error message:
"%1$.32s %2$.64s" includes the first
argument, then the second, in that order.
"%2$.64s %1$.32s" includes the second
argument, then the first.
If any argument is positional, all must be positional. This
Duplicates are allowed. This is legal even though it
includes the first argument twice:
"%1$.32s %2$.64s %1$.32s"
Gaps in positional number are not allowed. This is illegal
$2 is missing:
Use the following procedure to add new error messages:
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:
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'"
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.
Make a full build (configure +
make). A make all is
insufficient to build the
comp_err will generate the
errmsg.sys files, as well as the header
sql_state.h in the
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-utf8.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.
Note: This section is included for historical purposes. In practice, no new error messages should be added to error message files for versions of MySQL prior to 5.0.3. Doing so and merging the messages upward would cause error numbers to change in more recent versions.
Before MySQL 5.0.3, error messages are stored in
errmsg.txt files in the language directories
sql/share. The files have names like
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
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
errmsg.txt files later.
Open the file
sql/share/english/errmsg.txt in an
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
For each new error message, add a
line to the
before the last line (
Adjust the value of
the new number of error messages.
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
file might not contain an entry for every symbol in
mysqld_error.h, those entries that are
sql_state.h must appear in the
same order as those for the corresponding entries in
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
Translate the error message for those languages that you
know by editing the files
Make a full build
make all is insufficient to