Troubleshooting
WordPress Db Error: Causes and How to Fix It

Short answer
A WordPress database error means a MySQL or MariaDB query failed. Common causes are wrong login details in wp-config, crashed tables, a plugin whose tables are missing or outdated, and an overloaded database server. Read the exact message, back up the database, then apply the fix for that error.
Key takeaways
- Each database error message points to a different cause, so read it closely.
- Connection errors usually mean wrong wp-config details or a server problem.
- The made by chain in debug log entries names the plugin or theme behind a failed query.
- Missing table or column errors usually need a plugin reinstall or database update.
- Back up the database before running any repair.
What is a WordPress database error?
A WordPress database error is a message saying a MySQL or MariaDB query failed, caused by bad login details, missing or damaged tables, a plugin's faulty query, or a database server that is overloaded or down.
WordPress stores posts, settings, users and plugin data in a database. Every page load runs queries against it. When a query fails, WordPress or PHP reports a database error.
These errors show up in different places:
- On every page, as Error establishing a database connection.
- In the admin, as One or more database tables are unavailable.
- In the debug log, as lines starting WordPress database error followed by the failed query.
- On screen, when debugging display is turned on.
The fix depends on which message you have. Back up the database before changing anything; our guide on backing up a WordPress database covers the options.
Which WordPress database error do you have?
Read the exact wording, because each message points to a different cause, from connection failures to missing tables and broken plugin queries.
| Error message | What it means | First step |
|---|---|---|
| Error establishing a database connection | WordPress cannot log in to the database | Check wp-config details and server status |
| One or more database tables are unavailable | Tables are damaged or locked | Run database repair |
| Table '...' doesn't exist | A query uses a table that is missing | Find which plugin owns the table |
| Unknown column '...' in 'field list' | Table structure is outdated | Run the plugin's database update |
| Duplicate entry '...' for key 'PRIMARY' | A row ID already exists | Check auto-increment and recent imports |
| MySQL server has gone away | Connection dropped mid-query | Check timeouts and packet size limits |
| Lock wait timeout exceeded or Deadlock | Queries blocked each other | Look for heavy plugins or cron jobs |
| The table is full or disk full | No space left | Free disk space or upgrade storage |
How do you fix Error establishing a database connection?
Check the database name, username, password and host in wp-config.php, confirm the database server is running, and ask your host if the server is overloaded.
This is the most common WordPress database error and blocks the whole site. Usually the login details changed, the database user lost its permissions, or the database server is down.
Our full guide to fixing Error establishing a database connection walks through every check in order.
How do you fix database tables that are unavailable or crashed?
Use the built-in repair tool by adding WP_ALLOW_REPAIR to wp-config.php, running the repair page, and then removing the line, or repair the tables in phpMyAdmin.
Tables can crash after a server crash, a full disk or an interrupted update. WordPress then shows a notice that tables need repair.
The quick version:
- Add
define( 'WP_ALLOW_REPAIR', true );to wp-config.php. - Visit
/wp-admin/maint/repair.phpon your site. - Click Repair Database.
- Remove the line from wp-config.php straight away, because the repair page needs no login.
Our guide on fixing database tables that need repair has more detail, including phpMyAdmin steps.
What does a WordPress database error in the debug log mean?
A debug log line starting with WordPress database error means one query failed; the line shows the error, the query, and the chain of functions that called it, which tells you which plugin or theme is responsible.
A typical entry looks like this:
WordPress database error Table 'wp_example_logs' doesn't exist for query
SELECT * FROM wp_example_logs WHERE ... made by require('wp-blog-header.php'),
..., do_action('init'), Example_Plugin->load_logs
Read the end of the made by chain. Function and class names usually point to a specific plugin, such as Example_Plugin above.
To get these lines, turn on logging as described in the Debugging in WordPress guide.
Our guides on enabling debug mode and reading the debug log show where the file lives.
Developers can see how WordPress runs queries and reports errors in the wpdb class reference.
How do you fix table doesn't exist or unknown column errors?
These errors usually mean a plugin's database setup never finished or its update did not run, so reinstall or update the plugin, run its database upgrade, or deactivate it if you no longer use it.
Plugins create their own tables on activation and change them during updates. If activation failed or a migration was interrupted, queries refer to tables or columns that are not there.
Try these steps:
- Identify the plugin from the table name or the made by chain.
- Look for a database update notice in the admin and run it.
- Deactivate and reactivate the plugin to trigger its setup again.
- Update the plugin to the latest version.
- If it still fails, contact the plugin's support with the log line.
WooCommerce shows its own update prompt. See WooCommerce database update required for that case.
Check the table prefix too. If you moved the site and the prefix in wp-config.php does not match the tables, WordPress cannot find anything. Our guide on finding your WordPress database name shows where to look.
How do you fix MySQL server has gone away?
This error means the connection closed during a query, usually because a query took longer than the server's timeout or sent more data than its maximum packet size.
The MySQL manual's page on the MySQL server has gone away error lists the common causes.
On WordPress sites it often appears during large imports, backups or migrations. Fixes include:
- Ask your host to raise
max_allowed_packetandwait_timeout. - Split large imports into smaller batches.
- Pause heavy backup jobs that run during busy hours.
- Upgrade the plan if the database server keeps restarting under load.
On shared hosting you usually cannot change these settings yourself, so open a ticket with the exact error.
How do you fix duplicate entry and deadlock errors?
Duplicate entry errors usually come from a broken auto-increment value or a repeated import, while deadlocks and lock timeouts come from heavy queries competing for the same rows.
For Duplicate entry for key PRIMARY, the table's auto-increment counter may be lower than the highest existing ID, often after a partial import. In phpMyAdmin, check the table's auto-increment value and set it higher than the largest ID. Back up first.
For Deadlock found or Lock wait timeout exceeded, look for plugins running many writes at once, such as statistics, logging, or scheduled tasks in WooCommerce. MariaDB's error code list helps decode the numbered errors.
Occasional deadlocks on busy stores are normal and the query is retried. Frequent ones point to a plugin worth replacing. Our guide on finding which plugin is causing a problem helps narrow it down.
Can WP-CLI help fix database errors?
Yes, WP-CLI has database commands to check, repair, optimize, export and query the database from the command line, which is faster and safer on large sites.
Useful commands from the wp db command reference:
wp db check
wp db repair
wp db optimize
wp db export backup.sql
Always run wp db export before any repair. WP-CLI uses the same login details as wp-config.php, so if it cannot connect either, the problem is the credentials or the server.
How do you prevent database errors in future?
Keep backups, update plugins carefully, clean out abandoned plugin tables, keep enough disk space, and choose hosting with a reliable database server.
Good habits:
- Back up daily on busy sites, and before every major update.
- Update on staging first for plugins that change their database.
- Remove unused plugins and their leftover tables.
- Watch disk usage, since a full disk causes crashes and corrupt tables.
- Optimize occasionally. Our guide on optimizing the WordPress database covers safe cleanup.
If errors keep returning even after these steps, ask your host to check the database server logs. Some problems only the host can see.
Frequently asked questions
Will a database error delete my content?
Usually not. Most errors mean a query failed, not that data is gone. Crashed tables can lose some rows in rare cases, which is why you should take a backup before running repairs and keep regular backups as a safety net.
Why do I see database errors only in the debug log?
WordPress hides database errors from visitors by default. They only appear on screen when debug display is turned on. A failed query from a plugin may not break the page you see, but it still writes a line to the log.
Can a plugin cause a WordPress database error?
Yes. Plugins run their own queries and create their own tables. A failed setup, an interrupted update, or a badly written query can all produce database errors. The function names in the debug log usually show which plugin is involved.
Should I edit the database directly in phpMyAdmin?
Only when you know exactly what you are changing and have a fresh backup. Direct edits skip WordPress safety checks, and a wrong change can break the site. For routine tasks, use WP-CLI or a well-reviewed plugin instead.
When should I contact my host about database errors?
Contact your host when the database server is unreachable, connection errors come and go, the disk is full, or you see server-level errors such as gone away or too many connections. These usually involve server settings you cannot change yourself.
Sources
- Debugging in WordPress WordPress Developer Resources
- wpdb class WordPress Developer Resources
- wp db WP-CLI Command Reference
- MySQL server has gone away MySQL Reference Manual
- MariaDB Error Codes MariaDB Knowledge Base
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


