Autoloader fatals when a mapped Pro module file is unavailable

[pirate-bot]

Summary

A frontend request can terminate with a fatal error when Neve attempts to autoload a mapped Neve Pro module whose file is unavailable.

Expected behavior: An unavailable mapped class file is treated as an unresolved class so normal loading can continue or fail gracefully.

Actual behavior: Neve 4.2.10 requires the missing file and PHP terminates the request with Failed opening required.

Impact: Affected sites return a fatal error on frontend requests while the missing mapped file is requested.

Customer context

• Product / area: Neve autoloading with Neve Pro namespace mapping
• Version: 4.2.10
• Environment: WordPress 7.0.4, PHP 8.4.24
• Integration / third party: Neve Pro add-on is active in the reported call path
• Reported error / symptom: Failed opening required '[redacted]/module.php'
• Impact: 3 telemetry occurrences across 2 sites between 2026-08-24 and 2026-08-28 during frontend requests.

Reproduction notes

1. Use Neve 4.2.10 with the Neve Pro namespace registered during theme bootstrap.
2. Trigger loading of a mapped Pro class whose derived module.php file is unavailable.
3. Observed production result: PHP terminates the frontend request with Failed opening required from the Neve autoloader.

Repository inspection confirms the required-file behavior in the affected tag. The exact originating Pro module is unavailable from the redacted telemetry path.

Diagnosis

Conclusion

Telemetry identifies an uncaught Failed opening required fatal at autoloader.php:148 in Neve 4.2.10 while loading a mapped Neve_Pro class. The v4.2.10 source unconditionally executes require for each mapped candidate, confirming that an absent module file terminates the request. This behavior predates 4.2.10, so the available history does not support classifying it as a regression in that release.

Where this likely occurs

• Frontend bootstrap registers Neve_Pro whenever NEVE_PRO_SPL_ROOT is defined in start.php lines 49-57, neve_run().
• autoloader.php lines 114-138, Neve\Autoloader::load_mapped_file(), derives a lowercase file path for mapped namespaces and delegates loading to require_file().
• In release v4.2.10, autoloader.php approx. lines 137-148, Neve\Autoloader::require_file(), unconditionally calls require $file; this aligns with the telemetry location.
• neve-pro-addon/includes/core/loader.php lines 184-222, Neve_Pro\Core\Loader::add_pluggable_modules(), calls class_exists() for the registered Pro module classes, reaching the theme autoloader.
• Commit 395e4b5dd (fix: improve autoloader and file inclusion handling) introduced guarded file handling after v4.2.10; the guarded behavior is present in v4.2.11.

Engineering notes

• The production report identifies an unavailable Pro module.php path but redacts the module directory, so the originating module cannot be determined from the available evidence.
• The fatal occurs in Neve code, not the bundled Themeisle SDK, matching the telemetry classification.
• Current autoloader.php lines 149-160, Neve\Autoloader::require_file(), checks declaration and file readability before inclusion. This indicates the inspected main-branch code no longer exhibits the v4.2.10 behavior.

Test coverage status

• tests/test-neve-autoloader.php lines 63-79, TestNeveAutoloader::testMissingMappedFileReturnsFalse(), explicitly covers a registered mapped namespace with no class file and expects false rather than a fatal.
• The test is a theme autoloader fixture; no inspected test identifies the redacted Pro module path from telemetry.

What to verify or explore next

• May be worth reproducing on an installation pinned to Neve 4.2.10 with a registered Neve_Pro namespace and an unavailable mapped module file.
• Check whether the two affected sites remained on 4.2.10 after v4.2.11 became available and whether updating eliminates the crash fingerprint.
• If the unredacted telemetry path is available internally, compare its module directory with the Pro add-on release contents.

Unknowns / follow-up

• The exact missing module and why its file was unavailable are unknown because the telemetry path is redacted.
• No customer-site inspection or runtime reproduction was performed.

Confidence

Confidence: 98/100

Production telemetry records a frontend fatal in Neve 4.2.10, and the tagged source unconditionally required mapped files without an availability check. The current source and dedicated test show this failure mode was subsequently addressed; the reported 4.2.10 crash remains a distinct release defect worth tracking.

Crash telemetry

Occurrences	3
Distinct sites	2
First seen	2026-08-24 11:29 UTC
Last seen	2026-08-28 17:17 UTC
Crash location	product:autoloader.php:148
Request context	frontend
Inside Themeisle SDK	no
Product versions	4.2.10
WP versions	7.0.4
PHP versions	8.4.24
SDK versions	3.3.59

---

Source: automated crash report — neve, fingerprint 86eb21687c37d1398209adf69b079015
Generated by bug-report-triage (ID: bug-report-triage_6a9275be808057.76293198)