(mysql.info.gz) Bug reports
Info Catalog
(mysql.info.gz) Asking questions
(mysql.info.gz) Questions
(mysql.info.gz) Answering questions
1.4.1.3 How to Report Bugs or Problems
......................................
The normal place to report bugs is `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 will
also be able to enter new reports.
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 will help you write
your report correctly so that you don't waste your time doing things
that may not help us much or at all.
We encourage everyone to use the `mysqlbug' script to generate a bug
report (or a report about any problem). `mysqlbug' can be found in the
`scripts' directory (source distribution) and in the `bin' directory
under your MySQL installation directory (binary distribution). If you
are unable to use `mysqlbug' (for example, if you are running on
Windows), it is still vital that you include all the necessary
information noted in this section (most importantly, a description of
the operating system and the MySQL version).
The `mysqlbug' script 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. 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 the
included test case or by running the shell or Perl script that is
included in the bug report.
All bugs posted in the bugs database at `http://bugs.mysql.com/' will
be corrected or documented in the next MySQL release. If only minor
code changes are needed to correct a problem, we may also post a patch
that fixes the problem.
If you have found a sensitive security bug in MySQL, you can send email
to <security@mysql.com>.
If you have a repeatable bug report, please report it to the bugs
database at `http://bugs.mysql.com/'. Note that even in this case it's
good to run the `mysqlbug' script first to find information about your
system. Any bug that we are able to repeat has a high chance of being
fixed in the next MySQL release.
To report other problems, you can use one of the MySQL mailing lists.
Remember that it is possible for us to respond to a message 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 is this:
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 initial report.
The most common errors made in bug reports are (a) not including the
version number of the MySQL distribution used, and (b) not fully
describing the platform on which the MySQL server is installed
(including the platform type and version number). This is highly
relevant information, and in 99 cases out of 100, the bug report is
useless without it. 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. Sometimes the error is
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 use. Note that every
compiling problem should be regarded as a bug and reported accordingly.
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. Reproduceable test case.
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 using programs, it is better that the error message reported
exactly matches the one that the program produces. (Even the
lettercase should be observed.) You should never try to reproduce from
memory what the error message was; instead, copy and paste the entire
message into your report.
If you have a problem with Connector/ODBC (MyODBC), please try to
generate a trace file and send it with your report. MyODBC bug
report.
Please remember that many of the people who will read your report will
do so using an 80-column display. When generating reports or examples
using the `mysql' command-line tool, you should therefore use the
`--vertical' option (or the `\G' statement terminator) for output that
would exceed the available width for such a display (for example, with
the `EXPLAIN SELECT' statement; see the example later in this section).
Please include the following information in your report:
* The version number of the MySQL distribution you are using (for
example, MySQL 4.0.12). 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 directory.
* 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 command `uname -a'.
* 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, the
name and version number of the compiler used are needed. If you
have a binary distribution, the distribution name is needed.
* 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 query that crashed
`mysqld'. You can usually find this out by running `mysqld' with
query logging enabled, and then looking in the log after `mysqld'
crashes Using log files.
* If a database table is related to the problem, include the output
from `mysqldump --no-data DB_NAME TBL_NAME'. This is very easy to
do and is a powerful way to get information about any table in a
database. The information will help us create a situation
matching the one you have.
* For speed-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 `SELECT' statement produces. You
should also include the output from `SHOW CREATE TABLE TBL_NAME'
for each involved table. The more information you give about your
situation, the more likely it is that someone can help you.
The following is an example of a very good bug report. It should
be posted with the `mysqlbug' script. The example uses the `mysql'
command-line tool. Note the use of the `\G' statement terminator
for statements whose output width would otherwise exceed that of
an 80-column display device.
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G
<output from SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<output from EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A short version of the output from SELECT,
including the time taken to run the query>
mysql> SHOW STATUS;
<output from SHOW STATUS>
* If a bug or problem occurs while running `mysqld', try to provide
an input script that will reproduce 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 post it on
`http://bugs.mysql.com/' for high-priority treatment.
If you can't provide a script, you should at least include the
output from `mysqladmin variables extended-status processlist' in
your mail 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 mailed to the mailing list (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 think that the MySQL server produces a strange result from
a query, include not only the result, but also your opinion of
what the result should be, and an account describing the basis for
your opinion.
* When giving an example of the problem, it's better to use the
variable names, table names, and so on that exist in your actual
situation than to come up with new names. The problem could be
related to the name of a variable or table. 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. In case
you have data that you don't want to show to others, 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, then 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
keys to answers and are very relevant. It is never a bad idea to
include them. If you use any modules, such as Perl or PHP, please
include the version numbers of those as well.
* 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 directory.
* 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 will 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 exactly what the purpose of the patch is, we
won't use it. Test cases will help us here. Show that the patch
will handle 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 you get a `parse error', 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 at `http://dev.mysql.com/doc/' doesn't cover the syntax you
are using, MySQL Server doesn't support your query. In this case,
your only options are to implement the syntax yourself or email
<licensing@mysql.com> and ask for an offer to implement it.
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 Server.
News.
* If your problem is that your data appears corrupt or you get errors
when you access a particular table, you should first check and
then try to repair your tables with `CHECK TABLE' and `REPAIR
TABLE' or with `myisamchk'. MySQL Database Administration.
If you are running Windows, please verify that
`lower_case_table_names' is 1 or 2 with `SHOW VARIABLES LIKE
'lower_case_table_names''.
* 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 `.err' suffix in the name.)
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. What is crashing.
* 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. Which version.
If you are a support customer, please cross-post the bug report to
<mysql-support@mysql.com> for higher-priority treatment, as well as to
the appropriate mailing list to see whether someone else has
experienced (and perhaps solved) the problem.
For information on reporting bugs in MyODBC, see MyODBC bug
report.
For solutions to some common problems, see Problems.
When answers are sent to you individually and not to the mailing list,
it is considered good etiquette to summarize the answers and send the
summary to the mailing list so that others may have the benefit of
responses you received that helped you solve your problem.
Info Catalog
(mysql.info.gz) Asking questions
(mysql.info.gz) Questions
(mysql.info.gz) Answering questions
automatically generated byinfo2html