A.2. Common Errors When Using MySQL Programs

MySQL 5.0

A.2. Common Errors When Using MySQL Programs

This section lists some errors that users frequently encounter when running MySQL programs. Although the problems show up when you try to run client programs, the solutions to many of the problems involves changing the configuration of the MySQL server.

A.2.1. Access denied

An error can have many causes. Often the problem is related to the MySQL accounts that the server allows client programs to use when connecting. See Section 5.8.8, “Causes of Errors”, and Section 5.8.2, “How the Privilege System Works”.

A.2.2. Can't connect to [local] MySQL server

A MySQL client on Unix can connect to the mysqld server in two different ways: By using a Unix socket file to connect through a file in the filesystem (default ), or by using TCP/IP, which connects through a port number. A Unix socket file connection is faster than TCP/IP, but can be used only when connecting to a server on the same computer. A Unix socket file is used if you don't specify a hostname or if you specify the special hostname .

If the MySQL server is running on Windows 9x or Me, you can connect only via TCP/IP. If the server is running on Windows NT, 2000, XP, or 2003 and is started with the option, you can also connect with named pipes if you run the client on the host where the server is running. The name of the named pipe is by default. If you don't give a hostname when connecting to mysqld, a MySQL client first tries to connect to the named pipe. If that doesn't work, it connects to the TCP/IP port. You can force the use of named pipes on Windows by using as the hostname.

The error (2002) normally means that there is no MySQL server running on the system or that you are using an incorrect Unix socket filename or TCP/IP port number when trying to connect to the server.

The error (2003) ' (10061) indicates that the network connection has been refused. You should check that there is a MySQL server running, that it has network connections enabled, the network port you specified is the one configured on the server, and that the TCP/IP port you are using has not been blocked by a firewall or port blocking service.

Start by checking whether there is a process named mysqld running on your server host. (Use ps xa | grep mysqld on Unix or the Task Manager on Windows.) If there is no such process, you should start the server. See Section 2.10.2.3, “Starting and Troubleshooting the MySQL Server”.

If a mysqld process is running, you can check it by trying the following commands. The port number or Unix socket filename might be different in your setup. represents the IP number of the machine where the server is running.

shell> 
shell> 
shell> 
shell> 
shell> 
shell> 

Note the use of backticks rather than forward quotes with the command; these cause the output of (that is, the current hostname) to be substituted into the mysqladmin command. If you have no command or are running on Windows, you can manually type the hostname of your machine (without backticks) following the option. You can also try to connect with TCP/IP to the local host.

Here are some reasons the error might occur:

  • mysqld is not running. Check your operating system's process list to ensure the mysqld process is present.

  • You're running a MySQL server on Windows with many TCP/IP connections to it. If you're experiencing that quite often your clients get that error, you can find a workaround here: Section A.2.2.1, “.

  • You are running on a system that uses MIT-pthreads. If you are running on a system that doesn't have native threads, mysqld uses the MIT-pthreads package. See Section 2.1.1, “Operating Systems Supported by MySQL”. However, not all MIT-pthreads versions support Unix socket files. On a system without socket file support, you must always specify the hostname explicitly when connecting to the server. Try using this command to check the connection to the server:

    shell> 
    
  • Someone has removed the Unix socket file that mysqld uses ( by default). For example, you might have a cron job that removes old files from the directory. You can always run mysqladmin version to check whether the Unix socket file that mysqladmin is trying to use really exists. The fix in this case is to change the cron job to not remove or to place the socket file somewhere else. See Section A.4.5, “How to Protect or Change the MySQL Unix Socket File”.

  • You have started the mysqld server with the option, but forgotten to tell client programs the new name of the socket file. If you change the socket pathname for the server, you must also notify the MySQL clients. You can do this by providing the same option when you run client programs. You also need to ensure that clients have permission to access the file. To find out where the socket file is, you can do:

    shell> 
    

    See Section A.4.5, “How to Protect or Change the MySQL Unix Socket File”.

  • You are using Linux and one server thread has died (dumped core). In this case, you must kill the other mysqld threads (for example, with or with the script) before you can restart the MySQL server. See Section A.4.2, “What to Do If MySQL Keeps Crashing”.

  • The server or client program might not have the proper access privileges for the directory that holds the Unix socket file or the socket file itself. In this case, you must either change the access privileges for the directory or socket file so that the server and clients can access them, or restart mysqld with a option that specifies a socket filename in a directory where the server can create it and where client programs can access it.

If you get the error message , you can try the following things to find out what the problem is:

  • Check whether the server is running on that host by executing and pressing the Enter key a couple of times. (3306 is the default MySQL port number. Change the value if your server is listening to a different port.) If there is a MySQL server running and listening to the port, you should get a response that includes the server's version number. If you get an error such as , then there is no server running on the given port.

  • If the server is running on the local host, try using mysqladmin -h localhost variables to connect using the Unix socket file. Verify the TCP/IP port number that the server is configured to listen to (it is the value of the variable.)

  • Make sure that your mysqld server was not started with the option. If it was, you cannot connect to it using TCP/IP.

  • Check to make sure that there is no firewall blocking access to MySQL. Applications such as ZoneAlarm and the Windows XP personal firewall may need to be configured to allow external access to a MySQL server.

A.2.2.1. 

When you're running a MySQL server on Windows with many TCP/IP connections to it, and you're experiencing that quite often your clients get a error, the reason might be that Windows doesn't allow for enough ephemeral (short-lived) ports to serve those connections.

By default, Windows allows 5000 ephemeral (short-lived) TCP ports to the user. After any port is closed it will remain in a status for 120 seconds. This status allows the connection to be reused at a much lower cost than reinitializing a brand new connection. However, the port will not be available again until this time expires.

With a small stack of available TCP ports (5000) and a high number of TCP ports being open and closed over a short period of time along with the status you have a good chance for running out of ports. There are two ways to address this problem:

  • Reduce the number of TCP ports consumed quickly by investigating connection pooling or persistent connections where possible

  • Tune some settings in the Windows registry (see below)

IMPORTANT: The following procedure involves modifying the Windows registry. Before you modify the registry, make sure to back it up and make sure that you understand how to restore the registry if a problem occurs. For information about how to back up, restore, and edit the registry, view the following article in the Microsoft Knowledge Base: http://support.microsoft.com/kb/256986/EN-US/.

  1. Start Registry Editor ().

  2. Locate the following key in the registry:

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
    
  3. On the menu, click , and then add the following registry value:

    Value Name: MaxUserPort
    Data Type: REG_DWORD
    Value: 65534
    

    This sets the number of ephemeral ports available to any user. The valid range is between 5000 and 65534 (decimal). The default value is 0x1388 (5000 decimal).

  4. On the menu, click , and then add the following registry value:

    Value Name: TcpTimedWaitDelay
    Data Type: REG_DWORD
    Value: 30
    

    This sets the number of seconds to hold a TCP port connection in state before closing. The valid range is between 0 (zero) and 300 (decimal). The default value is 0x78 (120 decimal).

  5. Quit Registry Editor.

  6. Reboot the machine.

Note: Undoing the above should be as simple as deleting the registry entries you've created.

A.2.3. Client does not support authentication protocol

MySQL 5.0 uses an authentication protocol based on a password hashing algorithm that is incompatible with that used by older (pre-4.1) clients. If you upgrade the server from 4.0, attempts to connect to it with an older client may fail with the following message:

shell> 
Client does not support authentication protocol requested
by server; consider upgrading MySQL client

To solve this problem, you should use one of the following approaches:

  • Upgrade all client programs to use a 4.1.1 or newer client library.

  • When connecting to the server with a pre-4.1 client program, use an account that still has a pre-4.1-style password.

  • Reset the password to pre-4.1 style for each user that needs to use a pre-4.1 client program. This can be done using the statement and the function:

    mysql> 
        -> '@'' = OLD_PASSWORD('');
    

    Alternatively, use and :

    mysql> ')
        -> ' AND User = '';
    mysql> 
    

    Substitute the password you want to use for “” in the preceding examples. MySQL cannot tell you what the original password was, so you'll need to pick a new one.

  • Tell the server to use the older password hashing algorithm:

    1. Start mysqld with the option.

    2. Assign an old-format password to each account that has had its password updated to the longer 4.1 format. You can identify these accounts with the following query:

      mysql> 
          -> 
      

      For each account record displayed by the query, use the and values and assign a password using the function and either or , as described earlier.

Note: In older versions of PHP, the extension does not support the authentication protocol in MySQL 4.1.1 and higher. This is true regardless of the PHP version being used. If you wish to use the extension with MySQL 4.1 or newer, you may need to follow one of the options discussed above for configuring MySQL to work with old clients. The extension (stands for "MySQL, Improved"; added in PHP 5) is compatible with the improved password hashing employed in MySQL 4.1 and higher, and no special configuration of MySQL need be done to use this MySQL client library. For more information about the extension, see http://php.net/mysqli.

It may also be possible to compile the older extension against the new MySQL client library. This is beyond the scope of this Manual; consult the PHP documentation for more information. You also be able to obtain assistance with these issues in our MySQL with PHP forum.

For additional background on password hashing and authentication, see Section 5.8.9, “Password Hashing as of MySQL 4.1”.

A.2.4. Password Fails When Entered Interactively

MySQL client programs prompt for a password when invoked with a or option that has no following password value:

shell>  -p
Enter password:

On some systems, you may find that your password works when specified in an option file or on the command line, but not when you enter it interactively at the prompt. This occurs when the library provided by the system to read passwords limits password values to a small number of characters (typically eight). That is a problem with the system library, not with MySQL. To work around it, change your MySQL password to a value that is eight or fewer characters long, or put your password in an option file.

A.2.5. Host 'host_name' is blocked

If you get the following error, it means that mysqld has received many connect requests from the host ' that have been interrupted in the middle:

Host '' is blocked because of many connection errors.
Unblock with 'mysqladmin flush-hosts'

The number of interrupted connect requests allowed is determined by the value of the system variable. After failed requests, mysqld assumes that something is wrong (for example, that someone is trying to break in), and blocks the host from further connections until you execute a mysqladmin flush-hosts command or issue a statement. See Section 5.2.2, “Server System Variables”.

By default, mysqld blocks a host after 10 connection errors. You can adjust the value by starting the server like this:

shell> 

If you get this error message for a given host, you should first verify that there isn't anything wrong with TCP/IP connections from that host. If you are having network problems, it does you no good to increase the value of the variable.

A.2.6. Too many connections

If you get a error when you try to connect to the mysqld server, this means that all available connections are in use by other clients.

The number of connections allowed is controlled by the system variable. Its default value is 100. If you need to support more connections, you should restart mysqld with a larger value for this variable.

mysqld actually allows clients to connect. The extra connection is reserved for use by accounts that have the privilege. By granting the privilege to administrators and not to normal users (who should not need it), an administrator can connect to the server and use to diagnose problems even if the maximum number of unprivileged clients are connected. See Section 13.5.4.19, “ Syntax”.

The maximum number of connections MySQL can support depends on the quality of the thread library on a given platform. Linux or Solaris should be able to support 500-1000 simultaneous connections, depending on how much RAM you have and what your clients are doing. Static Linux binaries provided by MySQL AB can support up to 4000 connections.

A.2.7. Out of memory

If you issue a query using the mysql client program and receive an error like the following one, it means that mysql does not have enough memory to store the entire query result:

mysql: Out of memory at line 42, 'malloc.c'
mysql: needed 8136 byte (8k), memory in use: 12481367 bytes (12189k)
ERROR 2008: MySQL client ran out of memory

To remedy the problem, first check whether your query is correct. Is it reasonable that it should return so many rows? If not, correct the query and try again. Otherwise, you can invoke mysql with the option. This causes it to use the C API function to retrieve the result set, which places less of a load on the client (but more on the server).

A.2.8. MySQL server has gone away

This section also covers the related error.

The most common reason for the error is that the server timed out and closed the connection. In this case, you normally get one of the following error codes (which one you get is operating system-dependent):

Error Code Description
The client couldn't send a question to the server.
The client didn't get an error when writing to the server, but it didn't get a full answer (or any answer) to the question.

By default, the server closes the connection after eight hours if nothing has happened. You can change the time limit by setting the variable when you start mysqld. See Section 5.2.2, “Server System Variables”.

If you have a script, you just have to issue the query again for the client to do an automatic reconnection. This assumes that you have automatic reconnection in the client enabled (which is the default for the command-line client).

Some other common reasons for the error are:

  • You (or the db administrator) has killed the running thread with a statement or a mysqladmin kill command.

  • You tried to run a query after closing the connection to the server. This indicates a logic error in the application that should be corrected.

  • A client application running on a different host does not have the necessary privileges to connect to the MySQL server from that host.

  • You got a timeout from the TCP/IP connection on the client side. This may happen if you have been using the commands: or . In this case increasing the timeout may help solve the problem.

  • You have encountered a timeout on the server side and the automatic reconnection in the client is disabled (the flag in the structure is equal to 0).

  • You are using a Windows client and the server had dropped the connection (probably because expired) before the command was issued.

    The problem on Windows is that in some cases MySQL doesn't get an error from the OS when writing to the TCP/IP connection to the server, but instead gets the error when trying to read the answer from connection.

    Prior to MySQL 5.0.19, even if the flag in the structure is equal to 1, MySQL does not automatically reconnect and re-issue the query as it doesn't know if the server did get the original query or not.

    The solution to this is to either do a on the connection if there has been a long time since the last query (this is what does) or set on the mysqld server so high that it in practice never times out.

  • You can also get these errors if you send a query to the server that is incorrect or too large. If mysqld receives a packet that is too large or out of order, it assumes that something has gone wrong with the client and closes the connection. If you need big queries (for example, if you are working with big columns), you can increase the query limit by setting the server's variable, which has a default value of 1MB. You may also need to increase the maximum packet size on the client end. More information on setting the packet size is given in Section A.2.9, “.

  • You also get a lost connection if you are sending a packet 16MB or larger if your client is older than 4.0.8 and your server is 4.0.8 and above, or the other way around.

  • It is also possible to see this error if hostname lookups fail (for example, if the DNS server on which your server or network relies goes down). This is because MySQL is dependent on the host system for name resolution, but has no way of knowing whether it is working — from MySQL's point of view the problem is indistinguishable from any other network timeout.

    You may also see the error if MySQL is started with the option.

  • You can also encounter this error with applications that fork child processes, all of which try to use the same connection to the MySQL server. This can be avoided by using a separate connection for each child process.

    Another networking issue that can cause this error occurs if if the MySQL port (default 3306) is blocked by your firewall, thus preventing any connections at all to the MySQL server.

  • You have encountered a bug where the server died while executing the query.

You can check whether the MySQL server died and restarted by executing mysqladmin version and examining the server's uptime. If the client connection was broken because mysqld crashed and restarted, you should concentrate on finding the reason for the crash. Start by checking whether issuing the query again kills the server again. See Section A.4.2, “What to Do If MySQL Keeps Crashing”.

You can get more information about the lost connections by starting mysqld with the option. This logs some of the disconnected errors in the file. See Section 5.12.1, “The Error Log”.

If you want to create a bug report regarding this problem, be sure that you include the following information:

See also Section A.2.10, “Communication Errors and Aborted Connections”, and Section 1.8, “How to Report Bugs or Problems”.

A.2.9. Packet too large

A communication packet is a single SQL statement sent to the MySQL server or a single row that is sent to the client.

The largest possible packet that can be transmitted to or from a MySQL 5.0 server or client is 1GB.

When a MySQL client or the mysqld server receives a packet bigger than bytes, it issues a error and closes the connection. With some clients, you may also get a error if the communication packet is too large.

Both the client and the server have their own variable, so if you want to handle big packets, you must increase this variable both in the client and in the server.

If you are using the mysql client program, its default variable is 16MB. To set a larger value, start mysql like this:

shell> 

That sets the packet size to 32MB.

The server's default value is 1MB. You can increase this if the server needs to handle big queries (for example, if you are working with big columns). For example, to set the variable to 16MB, start the server like this:

shell> 

You can also use an option file to set . For example, to set the size for the server to 16MB, add the following lines in an option file:

[mysqld]
max_allowed_packet=16M

It is safe to increase the value of this variable because the extra memory is allocated only when needed. For example, mysqld allocates more memory only when you issue a long query or when mysqld must return a large result row. The small default value of the variable is a precaution to catch incorrect packets between the client and server and also to ensure that you do not run out of memory by using large packets accidentally.

You can also get strange problems with large packets if you are using large values but have not given mysqld access to enough memory to handle the query. If you suspect this is the case, try adding ulimit -d 256000 to the beginning of the mysqld_safe script and restarting mysqld.

A.2.10. Communication Errors and Aborted Connections

The server error log can be a useful source of information about connection problems. See Section 5.12.1, “The Error Log”. If you start the server with the option, you might find messages like this in your error log:

010301 14:38:23  Aborted connection 854 to db: 'users' user: 'josh'

If messages appear in the error log, the cause can be any of the following:

  • The client program did not call before exiting.

  • The client had been sleeping more than or seconds without issuing any requests to the server. See Section 5.2.2, “Server System Variables”.

  • The client program ended abruptly in the middle of a data transfer.

When any of these things happen, the server increments the status variable.

The server increments the status variable when the following things happen:

  • A client doesn't have privileges to connect to a database.

  • A client uses an incorrect password.

  • A connection packet doesn't contain the right information.

  • It takes more than seconds to get a connect packet. See Section 5.2.2, “Server System Variables”.

If these kinds of things happen, it might indicate that someone is trying to break into your server!

Other reasons for problems with aborted clients or aborted connections:

  • Use of Ethernet protocol with Linux, both half and full duplex. Many Linux Ethernet drivers have this bug. You should test for this bug by transferring a huge file via FTP between the client and server machines. If a transfer goes in burst-pause-burst-pause mode, you are experiencing a Linux duplex syndrome. The only solution is switching the duplex mode for both your network card and hub/switch to either full duplex or to half duplex and testing the results to determine the best setting.

  • Some problem with the thread library that causes interrupts on reads.

  • Badly configured TCP/IP.

  • Faulty Ethernets, hubs, switches, cables, and so forth. This can be diagnosed properly only by replacing hardware.

  • The variable value is too small or queries require more memory than you have allocated for mysqld. See Section A.2.9, “.

See also Section A.2.8, “.

A.2.11. The table is full

There are several ways a full-table error can occur:

  • You are using a MySQL server older than 3.23 and an in-memory temporary table becomes larger than bytes. To avoid this problem, you can use the option to make mysqld increase the temporary table size or use the SQL option before you issue the problematic query. See Section 13.5.3, “ Syntax”.

    You can also start mysqld with the option. This is exactly the same as using for all queries.

    As of MySQL 3.23, this problem should not occur. If an in-memory temporary table becomes larger than , the server automatically converts it to a disk-based table.

  • You are using tables and run out of room in the tablespace. In this case, the solution is to extend the tablespace. See Section 14.2.7, “Adding and Removing Data and Log Files”.

  • You are using or tables on an operating system that supports files only up to 2GB in size and you have hit this limit for the data file or index file.

  • You are using a table and the space required for the table exceeds what is allowed by the internal pointer size. If you don't specify the table option when you create a table, MySQL uses the system variable. From MySQL 5.0.6 on, the default value is 6 bytes, which is enough to allow 256TB of data. Before MySQL 5.0.6, the default value is 4 bytes, which is enough to allow only 4GB of data. See Section 5.2.2, “Server System Variables”.

    You can check the maximum data/index sizes by using this statement:

    SHOW TABLE STATUS FROM database LIKE '';
    

    You also can use myisamchk -dv /path/to/table-index-file.

    If the pointer size is too small, you can fix the problem by using :

    ALTER TABLE  MAX_ROWS=1000000000 AVG_ROW_LENGTH=;
    

    You have to specify only for tables with or columns; in this case, MySQL can't optimize the space required based only on the number of rows.

A.2.12. Can't create/write to file

If you get an error of the following type for some queries, it means that MySQL cannot create a temporary file for the result set in the temporary directory:

Can't create/write to file '\\sqla3fe_0.ism'.

The preceding error is a typical message for Windows; the Unix message is similar.

One fix is to start mysqld with the option or to add the option to the section of your option file. For example, to specify a directory of , use these lines:

[mysqld]
tmpdir=C:/temp

The directory must exist and have sufficient space for the MySQL server to write to. See Section 4.3.2, “Using Option Files”.

Another cause of this error can be permissions issues. Make sure that the MySQL server can write to the directory.

Check also the error code that you get with perror. One reason the server cannot write to a table is that the filesystem is full:

shell> 
Error code  28:  No space left on device

A.2.13. Commands out of sync

If you get in your client code, you are calling client functions in the wrong order.

This can happen, for example, if you are using and try to execute a new query before you have called . It can also happen if you try to execute two queries that return data without calling or in between.

A.2.14. Ignoring user

If you get the following error, it means that when mysqld was started or when it reloaded the grant tables, it found an account in the table that had an invalid password.

'@''; ignoring user

As a result, the account is simply ignored by the permission system.

The following list indicates possible causes of and fixes for this problem:

  • You may be running a new version of mysqld with an old table. You can check this by executing mysqlshow mysql user to see whether the column is shorter than 16 characters. If so, you can correct this condition by running the script.

  • The account has an old password (eight characters long) and you didn't start mysqld with the option. Update the account in the table to have a new password or restart mysqld with the option.

  • You have specified a password in the table without using the function. Use mysql to update the account in the table with a new password, making sure to use the function:

    mysql> ')
        -> ' AND Host='';
    

A.2.15. Table 'tbl_name' doesn't exist

If you get either of the following errors, it usually means that no table exists in the default database with the given name:

Table '' doesn't exist
Can't find file: '' (errno: 2)

In some cases, it may be that the table does exist but that you are referring to it incorrectly:

  • Because MySQL uses directories and files to store databases and tables, database and table names are case sensitive if they are located on a filesystem that has case-sensitive filenames.

  • Even for filesystems that are not case sensitive, such as on Windows, all references to a given table within a query must use the same lettercase.

You can check which tables are in the default database with . See Section 13.5.4, “ Syntax”.

A.2.16. Can't initialize character set

You might see an error like this if you have character set problems:

MySQL Connection Failed: Can't initialize character set 

This error can have any of the following causes:

  • The character set is a multi-byte character set and you have no support for the character set in the client. In this case, you need to recompile the client by running configure with the or option. See Section 2.9.2, “Typical configure Options”.

    All standard MySQL binaries are compiled with , which enables support for all multi-byte character sets. See Section 5.11.1, “The Character Set Used for Data and Sorting”.

  • The character set is a simple character set that is not compiled into mysqld, and the character set definition files are not in the place where the client expects to find them.

    In this case, you need to use one of the following methods to solve the problem:

    • Recompile the client with support for the character set. See Section 2.9.2, “Typical configure Options”.

    • Specify to the client the directory where the character set definition files are located. For many clients, you can do this with the option.

    • Copy the character definition files to the path where the client expects them to be.

A.2.17. File Not Found

If you get , , or any other error with or from MySQL, it means that you haven't allocated enough file descriptors for the MySQL server. You can use the perror utility to get a description of what the error number means:

shell> 
Error code  23:  File table overflow
shell> 
Error code  24:  Too many open files
shell> 
Error code  11:  Resource temporarily unavailable

The problem here is that mysqld is trying to keep open too many files simultaneously. You can either tell mysqld not to open so many files at once or increase the number of file descriptors available to mysqld.

To tell mysqld to keep open fewer files at a time, you can make the table cache smaller by reducing the value of the system variable (the default value is 64). Reducing the value of also reduces the number of open files (the default value is 100).

To change the number of file descriptors available to mysqld, you can use the option to mysqld_safe or (as of MySQL 3.23.30) set the system variable. See Section 5.2.2, “Server System Variables”. The easiest way to set these values is to add an option to your option file. See Section 4.3.2, “Using Option Files”. If you have an old version of mysqld that doesn't support setting the open files limit, you can edit the mysqld_safe script. There is a commented-out line ulimit -n 256 in the script. You can remove the ‘’ character to uncomment this line, and change the number to set the number of file descriptors to be made available to mysqld.

and ulimit can increase the number of file descriptors, but only up to the limit imposed by the operating system. There is also a “hard” limit that can be overridden only if you start mysqld_safe or mysqld as (just remember that you also need to start the server with the option in this case so that it does not continue to run as after it starts up). If you need to increase the operating system limit on the number of file descriptors available to each process, consult the documentation for your system.

Note: If you run the tcsh shell, ulimit does not work! tcsh also reports incorrect values when you ask for the current limits. In this case, you should start mysqld_safe using sh.