The “MySQL server has gone away” error means the connection between PHP and MySQL was dropped before the query could complete. PHP tried to talk to the database, but the database was no longer listening on the other end of that connection.
It is one of the more frustrating WordPress errors because it can appear intermittently, disappear on its own, and leave no obvious explanation in the WordPress dashboard. Understanding what causes it makes it significantly easier to diagnose and fix.
What the error actually means
When PHP connects to MySQL, it opens a connection that stays open for the duration of the script. MySQL keeps idle connections alive for a configurable period of time – the
wait_timeout
setting. If the connection sits idle longer than that timeout, MySQL closes it on its server side.
The problem is PHP does not always know the connection was closed. If a script opens a database connection early, does something else for a while (an API call, a file operation, a long loop), and then tries to run a query, MySQL may have already closed the connection. PHP attempts to send the query on a dead connection and gets the “server has gone away” error back.
This is the most common cause, but not the only one. The full list:
Connection timeout
The connection was idle longer than MySQL’s
wait_timeout
allows. MySQL closed it. PHP tried to use it. Default
wait_timeout
on many servers is 28800 seconds (8 hours), but hosting environments often set it lower – sometimes as low as 60 seconds – to free up connections faster on shared infrastructure.
Packet too large
MySQL has a
max_allowed_packet
setting that limits the size of a single query or result. If a query exceeds this limit – inserting a large blob, importing a big dataset, running a query with a very large IN() clause – MySQL drops the connection and returns this error.
On WordPress sites, this commonly happens during:
- Importing a large XML file via the WordPress importer
- Uploading large amounts of data through a plugin
- WooCommerce bulk operations
MySQL restarted
If MySQL restarts while a PHP script is running, all open connections are dropped immediately. Any subsequent query attempt returns “server has gone away”. This is less common in production but happens during maintenance, updates, or server restarts.
Corrupted or oversized result set
If MySQL tries to return a result that is too large to fit in its output buffer, it may drop the connection rather than send a partial result. This is less common but can happen with poorly optimized queries that return large numbers of rows without a LIMIT clause.
Server-side resource exhaustion
If MySQL runs out of memory or hits another resource limit, it may drop connections to recover. This typically produces other error messages alongside “server has gone away” and usually indicates a larger infrastructure problem.
How to diagnose it
Identify when it happens
Is it happening on a specific page or action, or randomly across the site?
If it happens on a specific action – importing data, submitting a large form, running a specific admin operation – the likely cause is either a large packet or a long-running script that lets the connection go idle.
If it happens randomly and unpredictably, the likely cause is connection timeout, particularly if your hosting environment has a short
wait_timeout
.
Check the WordPress debug log
Enable WordPress debug logging by adding these lines to wp-config.php:
php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );The debug log is saved to wp-content/debug.log. After enabling it, reproduce the error and check the log for database error messages. The log will often show which query failed, which gives you a clearer picture of what triggered the disconnection.
Check the MySQL error log
The MySQL error log records server-side events including connection drops, restarts, and resource issues. On managed hosting, your provider can check this log if you report the timestamp of the error. If you have server access, it is typically at /var/log/mysql/error.log.
Check wait_timeout
If you have access to MySQL, run:
sql
SHOW VARIABLES LIKE 'wait_timeout';
SHOW VARIABLES LIKE 'interactive_timeout';A very low value (under 60 seconds) combined with scripts that do significant work between queries is a likely cause of intermittent disconnections.
Check max_allowed_packet
sql
SHOW VARIABLES LIKE 'max_allowed_packet';If the value is low (under 16MB) and you are doing imports or bulk operations, this may be the cause.
How to fix it
For timeout-related disconnections
The cleanest fix at the application level is to reconnect when the connection drops rather than assuming the connection stays open. WordPress uses wpdb, which does not automatically reconnect after a timeout.
The wpdb class has a check_connection() method, but it is not called automatically before every query. For long-running scripts, you can call it explicitly:
php
if ( ! $wpdb->check_connection() ) {
// handle reconnection
}For WP-CLI scripts and long-running background processes, reconnecting before a batch of queries is good practice:
php
$wpdb->check_connection( false );If you are writing custom code that processes data in batches, run your database queries within each batch iteration rather than opening a connection at the start and expecting it to survive across the entire operation.
For large packet issues
If the error happens during an import or bulk operation, the
max_allowed_packet
value needs to be increased. On managed hosting, contact your provider to request an increase. A value of 64MB or 128MB is reasonable for most use cases.
If you are doing a one-time large import, consider breaking it into smaller files. The WordPress importer handles chunked imports better than a single large file.
For WordPress importer timeouts
Large WordPress XML imports are a common trigger for this error because the importer processes a large file in a single PHP execution, makes many database calls, and can run for a long time. If the database connection times out mid-import, you get this error and the import stops partway through.
Options:
- Use WP-CLI to run the import from the command line, which has no web timeout:
wp import file.xml --authors=create - Break the export file into smaller chunks using a tool like WXR Splitter before importing
- Use a migration plugin that handles chunked processing
For intermittent errors on live sites
If the error is happening occasionally on a live site without any obvious trigger, the most likely cause is a plugin or theme that holds a database connection open while doing something slow – an external API call, a slow file operation, a lengthy computation.
Use Query Monitor (a free WordPress plugin) to identify slow database operations and which code is responsible. Look for queries that show high execution time or queries that run during external HTTP requests.
For WooCommerce sites
WooCommerce performs significant database work during checkout – inventory checks, order creation, payment processing, email triggers. If any of these steps takes long enough to let the connection time out, or if a payment gateway API call is slow, you can get this error during checkout.
Ensure your payment gateway plugins are up to date. Check whether the error correlates with specific payment methods. Consider whether any checkout hooks are doing unnecessary database work.
What to tell your hosting provider
If you cannot resolve the error yourself or need the
wait_timeout
or
max_allowed_packet
settings adjusted, contact your hosting provider with:
- The exact error message as it appeared
- When it happens (specific page, action, or random)
- Approximately how long the operation was running when it failed
- Whether it is intermittent or consistent
This gives them enough context to check the MySQL configuration and logs on the server side and determine whether a configuration change is needed.
Summary
“MySQL server has gone away” means the database connection was dropped before a query could complete. The most common causes are connection timeout (MySQL closed an idle connection before PHP used it), packet size limits (a query or result exceeded max_allowed_packet), and MySQL restarting mid-request.
Diagnose by identifying whether the error is tied to a specific action or random, enabling WordPress debug logging, and checking MySQL timeout and packet size settings. Fix by reconnecting before long operations in custom code, breaking large imports into smaller chunks, using WP-CLI for long-running operations, and requesting configuration changes from your hosting provider when the server defaults are too restrictive.