Make WordPress Core

Opened 7 years ago

Last modified 7 years ago

#41424 new enhancement

Use a better error message than "Error establishing a database connection" when site isn't found

Reported by: tthorp's profile tthorp Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version: 4.9
Component: Database Keywords: needs-patch needs-unit-tests
Focuses: multisite Cc:


In multisite, if this query returns no results, the database connection error is triggered:

SELECT blog_id FROM wp_blogs WHERE domain IN ( '' ) AND path IN ( '/' ) ORDER BY blog_id ASC LIMIT 1

I think the error should not mention database connection but allude to the fact that the site was not found.

For my use case, I had migrated a production database into QA and didn't update the domain to be so the connection failed.

I hope this is helpful. I'm not sure I know what the exact solution is but I thought the connection attempt had failed, when in fact the connection had been made but the data was not as expected. Also, the failure was not found in debug.log.

Change History (5)

#1 @SergeyBiryukov
7 years ago

  • Focuses multisite added

#2 @danielbachhuber
7 years ago

  • Summary changed from loose error message: Error establishing a database connection to Use a better error message than "Error establishing a database connection" when site isn't found

+1 to improving the error state when a site isn't found.

The source of this issue is ms_not_installed(), which calls dead_db():

function ms_not_installed( $domain, $path ) {
	global $wpdb;

	if ( ! is_admin() ) {

Calling dead_db() was added in r31657, which displays the generic db connection error. Limiting the contents of the error message was applied all the way back in r14317.

This is a commonly experienced issue when moving a multisite database between environments. If wp search-replace was performed incorrectly, or not at all, the end user will experience the cryptic error.

I can reproduce this issue by:

  1. Creating a new WordPress multisite instance with one site.
  2. Manually setting the domain value in the wp_blogs table to
  3. Manually editing the DOMAIN_CURRENT_SITE constant to

When visiting in my browser, I see:

Error establishing a database connection

On the command line, WP-CLI is a bit more helpful with:

Error: Site '' not found. Verify DOMAIN_CURRENT_SITE matches an existing site or use --url=<url> to override.

#3 @ptasker
7 years ago

+1 on this as well. Tired of seeing this one when moving sites around!

#4 @jeremyfelt
7 years ago

  • Keywords needs-patch needs-unit-tests added
  • Milestone changed from Awaiting Review to Future Release

It does seem like there's room to improve here.

For this scenario, adding /wp-admin/ to the URL will get a more descriptive (though still confusing) message that includes this text:

"Could not find site Searched for table wp_blogs in database wordpress_develop. Is that right?"

That's probably more along the lines of what we can do. Really, we could think about using wp_die() in ms_load_current_site_and_network() rather than returning false and causing dead_db(). A similar thing happens when a network cannot be found.

Is it okay to expose the table and database name or should we have something more general? I know we expose all of this behind /wp-admin/ which kind of defeats the purpose of the obfuscation. :)

#5 @dd32
7 years ago

I'm not sure I'd go with wp_die() in this case - given it's a potential route to end up at with an overloaded multisite database. The obfuscation is there for two main cases 1) to not put up a WordPress-branded error page when it's not WordPress's fault, and 2) not put information on a page that's likely to end up in indexes or be seen by people whom it's not useful to.

However, changing it from dead_db(); to die( "<h1>Site $domain not found.</h1>" ); (with some escaping) could achieve the same result in this case, while also giving enough of a hint as to what the issue is.

Note: See TracTickets for help on using tickets.