database – What causes the “max_user_connections” warning on the WordPress frontend?

First you want to enable errors $wpdbWP Database Abstraction:


Otherwise none of your DB connections will actually die and be aborted with e.g. \WP_Error, The default error code is a 500,

the following error occurs \wpdb::db_connect(),

Error establishing a database connection

There are two cases where db_connect() Comes in use:

  1. connect to db
  2. Check if there is a connection to the database

Only the first person is allowed bail. If the connection dies only during the probe, it will No die and don’t throw this error. Now the connection has been made by \wpdb_driver::connect(), which distributes a check if the connection is enabled and available. This tells you that your real problem is actually the connection itself. you can see it (no joke) in the following file:

# interface-wp-db-driver.php
abstract class wpdb_driver {

You better not think about whether there is any relation between the overall quality of WP core code and a deeper understanding of interfaces and abstract classes here.

Just before the DB connection is declared “failed” and the error will be removed, there is a fine line:

require_once WP_CONTENT_DIR . '/db-error.php';

It means that there is a peek loaded before everything dies. You can use it and start debugging mechanism there. You have the complete WP core available there. You can start logging those errors in some ELK/Kibana, Spark or whatever stack, some Sass or even Slack (or just to a text file). Enter your errors there, log what’s going on, dump routes, requests, db connection details, whatever you think might help you.

Leave a Comment