Skip to content

Make multisite show detailed error messages from ms_not_installed()#6239

Merged
swissspidy merged 12 commits intomainfrom
copilot/print-database-error-message
Feb 18, 2026
Merged

Make multisite show detailed error messages from ms_not_installed()#6239
swissspidy merged 12 commits intomainfrom
copilot/print-database-error-message

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Feb 12, 2026

WordPress multisite's ms_not_installed() shows detailed error messages only when is_admin() returns true. Without this, users see "Error establishing a database connection" instead of actionable details about missing tables or unresolved domains.

Changes

  • Runner.php: Set a pseudo WP_Screen object with in_admin() method before loading wp-settings.php to make is_admin() return true during multisite bootstrap

    • This ensures WordPress's ms_not_installed() displays the full detailed error message
    • Clean up the pseudo screen object after WordPress loads
    • Added ms_network_not_found hook for better error handling when network is not found
  • framework.feature: Added test scenario that simulates network not found by using --require with a PHP file that hooks into networks_pre_query filter and returns an empty array

Approach

This solution makes WordPress's own ms_not_installed() function provide detailed error messages by temporarily setting a pseudo screen object that makes is_admin() return true. The pseudo object is cleaned up immediately after WordPress loads, avoiding any side effects on the rest of the bootstrap process.

Before

Error: Error establishing a database connection.

After

Error: The site you have requested is not installed.
Run `wp core install` to create database tables.

(The actual detailed message varies based on what WordPress detects - missing tables, missing site data, etc.)

Original prompt

This section details on the original issue you should resolve

<issue_title>Print full database error for ms_not_installed</issue_title>
<issue_description>## Feature Request

Describe your use case and the problem you are facing

When an error occurs in the sunrise process (ms-settings.php), wp-cli prints the basic Error: Error establishing a database connection. message with no further context or information. This makes it hard to understand the actual error which is occurring; i.e. did wp-cli fail to connect to the database, or was it unable to resolve the domain in multisite?

We see customers hit this all the time after performing a database migration and forgetting to run a search-replace, running an incomplete search-replace, or forgetting to clear the object cache.

Describe the solution you'd like

This error typically happens when ms_load_current_site_and_network() in ms-settings is unable to resolve the domain, triggering ms_not_installed(). ms_not_installed() only prints a detailed error if is_admin(), otherwise printing the generic error.

wp-cli should instead show the detailed information that ms_not_installed() shows; namely, if the database table is missing or if the searched row is missing.

(p.s. wp-cli does show the Error: Site 'example.com/' not found. error in some cases, working on working out why it doesn't in this case)</issue_description>

<agent_instructions>Start by adding a test first to try to reproduce</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@danielbachhuber @rmccue Were you able to track down the root cause here? Could you provide Behat steps to reproduce the scenario?

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

@codecov
Copy link
Copy Markdown

codecov bot commented Feb 12, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copilot AI and others added 3 commits February 12, 2026 22:36
Define WP_ADMIN constant before loading WordPress to ensure is_admin() returns true,
allowing ms_not_installed() and similar functions to provide detailed error messages
instead of generic "Error establishing a database connection" messages.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Updated the fix to only define WP_ADMIN for multisite installations,
preserving the existing behavior for single-site installations and
not breaking the context system tests.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
- Clarified comment about when WP_ADMIN might already be defined
- Added comment to test explaining what detailed error we're checking for

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Copilot AI changed the title [WIP] Improve error reporting for database connection issues Define WP_ADMIN for multisite to show detailed database errors Feb 12, 2026
Copilot AI requested a review from swissspidy February 12, 2026 22:44
@swissspidy

This comment was marked as resolved.

Copilot AI and others added 2 commits February 15, 2026 22:59
The original approach of defining WP_ADMIN caused unintended side effects by
changing WordPress multisite bootstrap behavior, leading to extra database
errors and triggering the ms_site_not_found hook.

New approach: Enhance wp_die_handler to detect generic database error message
for multisite and replace it with detailed information about missing tables.
This provides the detailed error message without changing WordPress behavior.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
- Remove unnecessary prepared statement for SHOW TABLES query
- Improve error message to mention both multisite-install and backup restore
- Add additional context when tables exist but site not found

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

This comment was marked as resolved.

Copilot AI changed the title Define WP_ADMIN for multisite to show detailed database errors Enhance multisite database error messages in wp_die_handler Feb 15, 2026
@swissspidy

This comment was marked as resolved.

This comment was marked as resolved.

@swissspidy

This comment was marked as resolved.

- Removed get_multisite_db_error_message() logic from utils-wp.php
- Added ms_network_not_found hook in Runner.php for better error messages
- Set pseudo WP_Screen before loading wp-settings.php to make is_admin() return true
  This ensures WordPress's ms_not_installed() shows detailed error messages
- Clean up pseudo screen after WordPress loads
- Updated test to use --require with networks_pre_query filter to simulate missing network

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

This comment was marked as resolved.

Copilot AI changed the title Enhance multisite database error messages in wp_die_handler Make multisite show detailed error messages from ms_not_installed() Feb 17, 2026

This comment was marked as resolved.

@swissspidy swissspidy added this to the 3.0.0 milestone Feb 18, 2026
@swissspidy swissspidy merged commit fe5d672 into main Feb 18, 2026
69 checks passed
@swissspidy swissspidy deleted the copilot/print-database-error-message branch February 18, 2026 14:32
swissspidy added a commit that referenced this pull request Feb 19, 2026
Avoids side effects of `is_admin()` being defined for longer.

Follow-up to #6239.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Print full database error for ms_not_installed

3 participants