Block-theme maintenance page fatals when DOMDocument is unavailable

Summary

The maintenance-page frontend can terminate with Error: Class "DOMDocument" not found on a block-theme site where the PHP DOM extension is unavailable.

Expected behavior: The maintenance page remains available, including in environments without the DOM extension.

Actual behavior: Rendering the page reaches the block-theme style collection flow and throws an uncaught error.

Impact: Visitors receive a failed maintenance-page request rather than the configured page.

Customer context

• Product / area: LightStart / WP Maintenance Mode block-theme maintenance-page rendering
• Version: 2.6.23
• Environment: WordPress 7.0.2; PHP 8.4.23; frontend request
• Integration / third party: PHP DOM extension unavailable in the reported runtime
• Reported error / symptom: Error: Class "DOMDocument" not found
• Impact: 24 crash occurrences from one production site during the telemetry query window.

Reproduction notes

1. Use LightStart 2.6.23 with a block theme.
2. Configure a page to use the plugin maintenance-page template.
3. Run PHP without the DOM extension and request that page on the frontend.

Reported result: the wpmm_head callback terminates at DOMDocument construction with Class "DOMDocument" not found.

Reproduction status: Confirmed from production telemetry and matching released source; not locally executed.

Diagnosis

Conclusion

Production telemetry records an uncaught DOMDocument class error at the exact frontend callback call site. The released 2.6.23 source unconditionally constructs DOMDocument when the block-theme hook executes, with no availability guard. This is a confirmed product crash for the reported environment.

Where this likely occurs

• includes/classes/wp-maintenance-mode.php — WP_Maintenance_Mode::__construct() lines 83-87 registers remember_style_fse() on wpmm_head when wp_is_block_theme() reports a block theme.
• includes/classes/wp-maintenance-mode.php — WP_Maintenance_Mode::remember_style_fse() lines 1135-1145 invokes new DOMDocument() at line 1143, matching the telemetry location.
• views/wpmm-page-template.php — template body line 20 dispatches wpmm_head, matching the reported frontend stack.
• includes/classes/wp-maintenance-mode.php — WP_Maintenance_Mode::add_style_fse() lines 1155-1163 contains a second unguarded DOMDocument construction on the footer hook; the reported crash occurs earlier in remember_style_fse().
• Commit 2067407a2d72f06bc3369950d42fcef4f71d2e29 introduced the DOM-based block-theme style flow. v2.6.23 retains the affected lines.

Engineering notes

• composer.json declares ext-dom at line 22, but the captured production request demonstrates that the extension was unavailable at runtime. The inspected plugin source does not show a runtime check before the frontend callback creates the class.
• The reported stack confirms the callback is reachable through the product template on a frontend request. The behavior is scoped to the block-theme path observed in telemetry; classic-theme behavior was not inspected.
• This report is not inside Themeisle SDK code according to telemetry, and the relevant execution path is in the plugin repository.

Test coverage status

tests/frontend-behavior-test.php covers maintenance-page template selection at lines 47-69. No relevant coverage was found during inspection for block-theme hook execution or an unavailable DOM extension. Tests were not run for this triage-only investigation.

What to verify or explore next

• Reproduce with a block theme and a PHP runtime where the DOM extension is unavailable, then request the configured maintenance page as a visitor.
• Exercise both the wpmm_head and wpmm_footer callbacks under that environment.
• Run the frontend test suite after adding coverage for the block-theme rendering path.

Unknowns / follow-up

• The telemetry does not state why the PHP DOM extension was unavailable on the affected site.
• The affected-site count outside the reported one-site telemetry sample is unknown.

Confidence

Confidence: 98/100

The production crash telemetry is corroborated by the 2.6.23 source: the block-theme frontend hook directly instantiates DOMDocument without a runtime availability check. The exact failing call and request path match the reported stack trace.

Crash telemetry

Occurrences	24
Distinct sites	1
First seen	2026-08-04 11:12 UTC
Last seen	2026-08-04 11:33 UTC
Crash location	product:includes/classes/wp-maintenance-mode.php:1143
Request context	frontend
Inside Themeisle SDK	no
Product versions	2.6.23
WP versions	7.0.2
PHP versions	8.4.23
SDK versions	3.3.58

---

Source: automated crash report — wp-maintenance-mode, fingerprint 50864848570e37026475e16886df80eb
Generated by bug-report-triage (ID: bug-report-triage_6a7422fe6b3b73.55923934)