1.8. How to Report Bugs or Problems
Before posting a bug report about a problem, please try to verify
that it is a bug and that it has not been reported already:
Start by searching the MySQL online manual at
http://dev.mysql.com/doc/. We try to keep the manual up to
date by updating it frequently with solutions to newly found
problems. The change history
(http://dev.mysql.com/doc/mysql/en/news.html) can be
particularly useful since it is quite possible that a newer
version contains a solution to your problem.
If you get a parse error for a SQL statement, please check your
syntax closely. If you can't find something wrong with it, it's
extremely likely that your current version of MySQL Server
doesn't support the syntax you are using. If you are using the
current version and the manual doesn't cover the syntax that you
are using, MySQL Server doesn't support your statement. In this
case, your options are to implement the syntax yourself or email
<[email protected]> and ask for an offer to
If the manual covers the syntax you are using, but you have an
older version of MySQL Server, you should check the MySQL change
history to see when the syntax was implemented. In this case,
you have the option of upgrading to a newer version of MySQL
For solutions to some common problems, see
Appendix A, Problems and Common Errors.
Search the bugs database at
http://bugs.mysql.com/ to see whether the bug has
been reported and fixed.
Search the MySQL mailing list archives at
Section 1.7.1, “MySQL Mailing Lists”.
You can also use http://www.mysql.com/search/ to
search all the Web pages (including the manual) that are located
at the MySQL AB Web site.
If you can't find an answer in the manual, the bugs database, or the
mailing list archives, check with your local MySQL expert. If you
still can't find an answer to your question, please use the
following guidelines for reporting the bug.
The normal way to report bugs is to visit
http://bugs.mysql.com/, which is the address for our
bugs database. This database is public and can be browsed and
searched by anyone. If you log in to the system, you can enter new
reports. If you have no Web access, you can generate a bug report by
using the mysqlbug script described at the end of
Bugs posted in the bugs database at
http://bugs.mysql.com/ that are corrected for a given
release are noted in the change history.
If you have found a sensitive security bug in MySQL, you can send
To discuss problems with other users, you can use one of the MySQL
mailing lists. Section 1.7.1, “MySQL Mailing Lists”.
Writing a good bug report takes patience, but doing it right the
first time saves time both for us and for yourself. A good bug
report, containing a full test case for the bug, makes it very
likely that we will fix the bug in the next release. This section
helps you write your report correctly so that you don't waste your
time doing things that may not help us much or at all. Please read
this section carefully and make sure that all the information
described here is included in your report.
Preferably, you should test the problem using the latest production
or development version of MySQL Server before posting. Anyone should
be able to repeat the bug by just using
mysql test <
script_file on your test case or by running the shell or
Perl script that you include in the bug report. Any bug that we are
able to repeat has a high chance of being fixed in the next MySQL
It is most helpful when a good description of the problem is
included in the bug report. That is, give a good example of
everything you did that led to the problem and describe, in exact
detail, the problem itself. The best reports are those that include
a full example showing how to reproduce the bug or problem. See
Section E.1.6, “Making a Test Case If You Experience Table Corruption”.
Remember that it is possible for us to respond to a report
containing too much information, but not to one containing too
little. People often omit facts because they think they know the
cause of a problem and assume that some details don't matter. A good
principle to follow is that if you are in doubt about stating
something, state it. It is faster and less troublesome to write a
couple more lines in your report than to wait longer for the answer
if we must ask you to provide information that was missing from the
The most common errors made in bug reports are (a) not including the
version number of the MySQL distribution that you use, and (b) not
fully describing the platform on which the MySQL server is installed
(including the platform type and version number). These are highly
relevant pieces of information, and in 99 cases out of 100, the bug
report is useless without them. Very often we get questions like,
“Why doesn't this work for me?” Then we find that the
feature requested wasn't implemented in that MySQL version, or that
a bug described in a report has been fixed in newer MySQL versions.
Errors often are platform-dependent. In such cases, it is next to
impossible for us to fix anything without knowing the operating
system and the version number of the platform.
If you compiled MySQL from source, remember also to provide
information about your compiler if it is related to the problem.
Often people find bugs in compilers and think the problem is
MySQL-related. Most compilers are under development all the time and
become better version by version. To determine whether your problem
depends on your compiler, we need to know what compiler you used.
Note that every compiling problem should be regarded as a bug and
If a program produces an error message, it is very important to
include the message in your report. If we try to search for
something from the archives, it is better that the error message
reported exactly matches the one that the program produces. (Even
the lettercase should be observed.) It is best to copy and paste the
entire error message into your report. You should never try to
reproduce the message from memory.
If you have a problem with Connector/ODBC (MyODBC), please try to
generate a trace file and send it with your report. See
Section 18.104.22.168, “How to Report MyODBC Problems or Bugs”.
If your report includes long query output lines from test cases that
you run with the mysql command-line tool, you can
make the output more readable by using the
--vertical option or the
statement terminator. The
EXPLAIN SELECT example
later in this section demonstrates the use of
Please include the following information in your report:
The version number of the MySQL distribution you are using (for
example, MySQL 5.0.19). You can find out which version you are
running by executing mysqladmin version. The
mysqladmin program can be found in the
bin directory under your MySQL installation
The manufacturer and model of the machine on which you
experience the problem.
The operating system name and version. If you work with Windows,
you can usually get the name and version number by
double-clicking your My Computer icon and pulling down the
“Help/About Windows” menu. For most Unix-like
operating systems, you can get this information by executing the
Sometimes the amount of memory (real and virtual) is relevant.
If in doubt, include these values.
If you are using a source distribution of the MySQL software,
include the name and version number of the compiler that you
used. If you have a binary distribution, include the
If the problem occurs during compilation, include the exact
error messages and also a few lines of context around the
offending code in the file where the error occurs.
If mysqld died, you should also report the
statement that crashed mysqld. You can
usually get this information by running
mysqld with query logging enabled, and then
looking in the log after mysqld crashes. See
Section E.1.5, “Using Server Logs to Find Causes of Errors in mysqld”.
If a database table is related to the problem, include the
output from the
SHOW CREATE TABLE
statement in the bug report. This is a very easy way to get the
definition of any table in a database. The information helps us
create a situation matching the one that you have experienced.
For performance-related bugs or problems with
SELECT statements, you should always include
the output of
EXPLAIN SELECT ..., and at
least the number of rows that the
statement produces. You should also include the output from
SHOW CREATE TABLE
for each table
that is involved. The more information you provide about your
situation, the more likely it is that someone can help you.
The following is an example of a very good bug report. The
statements are run using the mysql
command-line tool. Note the use of the
statement terminator for statements that would otherwise provide
very long output lines that are difficult to read.
SHOW COLUMNS FROM ...\G
<output from SHOW COLUMNS>
EXPLAIN SELECT ...\G
<output from EXPLAIN>
<A short version of the output from SELECT,
including the time taken to run the query>
<output from SHOW STATUS>
If a bug or problem occurs while running
mysqld, try to provide an input script that
reproduces the anomaly. This script should include any necessary
source files. The more closely the script can reproduce your
situation, the better. If you can make a reproducible test case,
you should upload it to be attached to the bug report.
If you can't provide a script, you should at least include the
output from mysqladmin variables extended-status
processlist in your report to provide some information
on how your system is performing.
If you can't produce a test case with only a few rows, or if the
test table is too big to be included in the bug report (more
than 10 rows), you should dump your tables using
mysqldump and create a
README file that describes your problem.
Create a compressed archive of your files using
tar and gzip or
zip, and use FTP to transfer the archive to
ftp://ftp.mysql.com/pub/mysql/upload/. Then enter the problem into
our bugs database at http://bugs.mysql.com/.
If you believe that the MySQL server produces a strange result
from a statement, include not only the result, but also your
opinion of what the result should be, and an explanation
describing the basis for your opinion.
When you provide an example of the problem, it's better to use
the table names, variable names, and so forth that exist in your
actual situation than to come up with new names. The problem
could be related to the name of a table or variable. These cases
are rare, perhaps, but it is better to be safe than sorry. After
all, it should be easier for you to provide an example that uses
your actual situation, and it is by all means better for us. If
you have data that you don't want to be visible to others in the
bug report, you can use FTP to transfer it to
ftp://ftp.mysql.com/pub/mysql/upload/. If the information is really
top secret and you don't want to show it even to us, go ahead
and provide an example using other names, but please regard this
as the last choice.
Include all the options given to the relevant programs, if
possible. For example, indicate the options that you use when
you start the mysqld server, as well as the
options that you use to run any MySQL client programs. The
options to programs such as mysqld and
mysql, and to the
configure script, are often key to resolving
problems and are very relevant. It is never a bad idea to
include them. If your problem involves a program written in a
language such as Perl or PHP, please include the language
processor's version number, as well as the version for any
modules that the program uses. For example, if you have a Perl
script that uses the
DBD::mysql modules, include the version
numbers for Perl,
If your question is related to the privilege system, please
include the output of mysqlaccess, the output
of mysqladmin reload, and all the error
messages you get when trying to connect. When you test your
privileges, you should first run mysqlaccess.
After this, execute mysqladmin reload version
and try to connect with the program that gives you trouble.
mysqlaccess can be found in the
bin directory under your MySQL installation
If you have a patch for a bug, do include it. But don't assume
that the patch is all we need, or that we can use it, if you
don't provide some necessary information such as test cases
showing the bug that your patch fixes. We might find problems
with your patch or we might not understand it at all. If so, we
can't use it.
If we can't verify the exact purpose of the patch, we won't use
it. Test cases help us here. Show that the patch handles all the
situations that may occur. If we find a borderline case (even a
rare one) where the patch won't work, it may be useless.
Guesses about what the bug is, why it occurs, or what it depends
on are usually wrong. Even the MySQL team can't guess such
things without first using a debugger to determine the real
cause of a bug.
Indicate in your bug report that you have checked the reference
manual and mail archive so that others know you have tried to
solve the problem yourself.
If the problem is that your data appears corrupt or you get
errors when you access a particular table, you should first
check your tables and then try to repair them with
CHECK TABLE and
TABLE or with myisamchk. See
Chapter 5, Database Administration.
If you are running Windows, please verify the value of
lower_case_table_names using the
SHOW VARIABLES LIKE 'lower_case_table_names'
command. This variable affects how the server handles lettercase
of database and table names. Its effect for a given value should
be as described in Section 9.2.2, “Identifier Case Sensitivity”.
If you often get corrupted tables, you should try to find out
when and why this happens. In this case, the error log in the
MySQL data directory may contain some information about what
happened. (This is the file with the
suffix in the name.) See Section 5.11.2, “The Error Log”. Please
include any relevant information from this file in your bug
report. Normally mysqld should
never crash a table if nothing killed it in
the middle of an update. If you can find the cause of
mysqld dying, it's much easier for us to
provide you with a fix for the problem. See
Section A.1, “How to Determine What Is Causing a Problem”.
If possible, download and install the most recent version of
MySQL Server and check whether it solves your problem. All
versions of the MySQL software are thoroughly tested and should
work without problems. We believe in making everything as
backward-compatible as possible, and you should be able to
switch MySQL versions without difficulty. See
Section 2.1.2, “Choosing Which MySQL Distribution to Install”.
If you have no Web access and cannot report a bug by visiting
http://bugs.mysql.com/, you can use the
mysqlbug script to generate a bug report (or a
report about any problem). mysqlbug helps you
generate a report by determining much of the following information
automatically, but if something important is missing, please include
it with your message. mysqlbug can be found in
scripts directory (source distribution) and
bin directory under your MySQL
installation directory (binary distribution).