Skip to content

Autoloader fatals when a mapped Pro module file is unavailable #4605

Open
Bug
Open
Autoloader fatals when a mapped Pro module file is unavailable#4605
Bug
Assignees
girishpanchal30
Labels
bug-reportbug-report-triagecrash-report

Description

@pirate-bot
pirate-bot
opened on Aug 29, 2026

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)

Activity

  1. pirate-bot
    added
    bug-report
    bug-report-triage
    crash-report
    on Aug 29, 2026
  2. pirate-bot
    added the
    Bug
    issue type on Aug 29, 2026
  3. girishpanchal30
    self-assigned this
    on Sep 16, 2026

  4. girishpanchal30 commented on Sep 16, 2026

    @girishpanchal30
    girishpanchal30
    on Sep 16, 2026
    Contributor

    It was fixed in this PR #4572 and released in v4.2.11.

  5. poonam279 commented on Sep 16, 2026

    @poonam279
    poonam279
    on Sep 16, 2026

    🤖 Automated QA Repro Steps

    On Neve 4.2.10 a frontend request dies with a PHP fatal — visitors get "There has been a critical error on this website" — whenever the theme is asked for a Neve Pro class whose file is not on disk (half-finished Pro update, a file quarantined by a security scanner, a failed upload). Nothing in the UI triggers this, so step 1 simulates the unavailable file. The same unguarded file loading also covered Neve's Google fonts list, block patterns, the header/footer builder template and the dashboard/metabox/customizer scripts — that is what the edge cases below cover.

    Requires: Neve 4.2.10 (downgrade — current release is 4.2.12) with Neve Pro active, plus the Code Snippets plugin.

    Reproduce on Neve 4.2.10:

    1. Add a Code Snippet titled "QA missing Pro module", set to run everywhere, with this code:
      add_action( 'wp', function () { class_exists( 'Neve_Pro\Modules\Qa_Missing\Module' ); } );
    2. Activate the snippet.
    3. Open any frontend page as a logged-out visitor.
    • Bug: the page returns "There has been a critical error on this website", and debug.log records Failed opening required ... modules/qa_missing/module.php.
    • Fixed: on 4.2.11 and later the page renders normally and no fatal is logged — the unavailable class is simply skipped.

    Assumption: the reported sites hit a genuinely missing Pro module file (telemetry redacted the path); the snippet puts the theme in the same situation.

    Edge cases
    • Customizer → Typography → font family dropdown: the full Google fonts list still loads and a chosen font applies in the preview.
    • Appearance → Neve Options → Settings → turn on local Google fonts hosting, then load the frontend: fonts still render, and no requests go to fonts.googleapis.com in the Network tab.
    • Block editor → Patterns → Neve category: every Neve pattern is still listed and inserts correctly.
    • Customizer → Header/Footer builder: rows render and components can still be dragged between them.
    • Appearance → Neve Options and the Neve panel in the post editor sidebar both load fully, with no blank areas or console errors.

    Fix: #4572 (merged — shipped in Neve 4.2.11)

  6. pirate-bot commented on Oct 1, 2026

    @pirate-bot
    pirate-bot
    on Oct 1, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again (fingerprint c4d4bb8c241d5c5bf282276dc6957d5f): 61 occurrence(s) across 2 site(s), last seen 2026-09-30 21:42 UTC.
    Automated crash telemetry captured this again (fingerprint 4168481ca1eb88e0fb00b702a4c034b7): 60 occurrence(s) across 1 site(s), last seen 2026-09-30 21:51 UTC.
    Automated crash telemetry captured this again (fingerprint 17d854c541e3872ae15f471c2dab4314): 55 occurrence(s) across 2 site(s), last seen 2026-09-30 19:25 UTC.
    Automated crash telemetry captured this again (fingerprint 4380659d19c6ca9f7cdd579da5c9b351): 52 occurrence(s) across 1 site(s), last seen 2026-09-30 22:11 UTC.

    When a mapped class file is unavailable, REST abilities discovery can trigger a fatal error because Neve's autoloader unconditionally executes require $file instead of treating the class as absent. This is caused by Neve\Autoloader::require_file() in neve/autoloader.php (around lines 137–148 in affected tags v4.0.1 through v4.2.9), where an optional check like class_exists('\Neve\Abilities\Loader') attempts to load a file missing from those theme versions. A file readability and class declaration guard was introduced in commit 395e4b5dd58b5adc102f0936b417efa4ca6bf41e (present in v4.2.11) to prevent this fatal behavior.

    Source: automated crash report — neve, fingerprints c4d4bb8c241d5c5bf282276dc6957d5f, 4168481ca1eb88e0fb00b702a4c034b7, 17d854c541e3872ae15f471c2dab4314, 4380659d19c6ca9f7cdd579da5c9b351
    Generated by bug-report-triage (ID: bug-report-triage_6abdf7b7dca2e6.42446116)

  7. pirate-bot commented on Oct 3, 2026

    @pirate-bot
    pirate-bot
    on Oct 3, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again (fingerprint 9dca78f0cbaaf03db49eee2c6917a45d): 62 occurrence(s) across 4 site(s), last seen 2026-10-02 16:04 UTC.
    Automated crash telemetry captured this again (fingerprint 713344ee781693538acc5a85f25c8498): 39 occurrence(s) across 1 site(s), last seen 2026-10-02 15:35 UTC.

    During REST abilities discovery, Neve Pro's lookup for an unavailable theme class triggers a fatal error in Neve v4.2.5 and v4.2.9. The root cause is an unguarded require in Autoloader::require_file() within autoloader.php, which unconditionally attempts to load a mapped file that is absent from those theme tags. This behavior is tracked in GitHub issue #4605, and a file check guard addressing the defect is present starting in v4.2.11.

    Source: automated crash report — neve, fingerprints 9dca78f0cbaaf03db49eee2c6917a45d, 713344ee781693538acc5a85f25c8498
    Generated by bug-report-triage (ID: bug-report-triage_6ac09a67e431f7.97614907)

  8. pirate-bot commented on Oct 4, 2026

    @pirate-bot
    pirate-bot
    on Oct 4, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again (fingerprint 18e2b069532b3f53a61acf3630797885): 12 occurrence(s) across 2 site(s), last seen 2026-09-30 19:10 UTC.
    Automated crash telemetry captured this again (fingerprint 68fbe72cc9dc7b30b86710770945489f): 11 occurrence(s) across 2 site(s), last seen 2026-10-01 00:51 UTC.

    When a request triggers autoloading for a mapped class whose file is absent, such as \Neve\Abilities\Loader during Neve Pro ability discovery, the request terminates with a PHP fatal error. The root cause is that Neve\Autoloader::require_file() in autoloader.php calls an unconditional require without verifying file availability. This issue is tracked in existing issue #4605 and is resolved in version v4.2.11 with the introduction of file and declaration guards.

    Source: automated crash report — neve, fingerprints 18e2b069532b3f53a61acf3630797885, 68fbe72cc9dc7b30b86710770945489f
    Generated by bug-report-triage (ID: bug-report-triage_6ac1ebd86b8495.57070254)

  9. pirate-bot commented on Oct 6, 2026

    @pirate-bot
    pirate-bot
    on Oct 6, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again (fingerprint ac2bcb961043f733f89fd154cc3937e1): 32 occurrence(s) across 1 site(s), last seen 2026-10-06 01:48 UTC.
    Automated crash telemetry captured this again (fingerprint db9aa998047aa923b205f1baaf6ade3f): 27 occurrence(s) across 1 site(s), last seen 2026-10-06 02:50 UTC.
    Automated crash telemetry captured this again (fingerprint bc482ff6dce45b73e5084924263d3835): 21 occurrence(s) across 1 site(s), last seen 2026-10-06 01:45 UTC.
    Automated crash telemetry captured this again (fingerprint 62466cbf4f66487a59e51619370e5257): 13 occurrence(s) across 1 site(s), last seen 2026-10-05 23:14 UTC.

    During REST ability discovery, affected Neve installations (v3.8.11, v4.0.1, v4.1.3, and v4.1.4) encounter a fatal error resulting in Failed opening required .../loader.php. The root cause is that Neve\Autoloader::require_file() directly executes require $file without checking whether the mapped optional file exists, triggered when Neve Pro's Module::get_theme_owned_ids() checks for the absent \Neve\Abilities\Loader class. This issue is tracked in Neve issue #4605, and a guarded implementation with proper file-availability checks is included in v4.2.11 and later.

    Source: automated crash report — neve, fingerprints ac2bcb961043f733f89fd154cc3937e1, db9aa998047aa923b205f1baaf6ade3f, bc482ff6dce45b73e5084924263d3835, 62466cbf4f66487a59e51619370e5257
    Generated by bug-report-triage (ID: bug-report-triage_6ac48f09e57dd4.14356025)

  10. pirate-bot commented on Oct 9, 2026

    @pirate-bot
    pirate-bot
    on Oct 9, 2026
    CollaboratorAuthor

    Another customer requested this via support.

    Context: Pro user experiencing a PHP fatal error on line 148 of neve/autoloader.php (Failed opening required '/.../inc/abilities/loader.php') on a live client site after an incomplete or failed update, which locked them out of wp-admin.

    Source: HelpScout #3477454850

    Generated by feature-request-triage workflow (ID: feature-request-triage_6ac84adfc3a7b0.20251967)

  11. pirate-bot commented on Oct 14, 2026

    @pirate-bot
    pirate-bot
    on Oct 14, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again: 16 occurrence(s) across 1 site(s), last seen 2026-10-13 15:02 UTC.

    During REST requests that trigger Neve Pro ability-category discovery, Neve 4.2.3 encounters a fatal error when it attempts to load an optional theme ability class whose file is missing from that theme release. The root cause is located in autoloader.php, where Neve\Autoloader::require_file() unconditionally executes require $file without checking if the mapped file exists. This issue is resolved in Neve v4.2.11 and later, where file-presence checks were added to the autoloader.

    Source: automated crash report — neve, fingerprint 473273430f60495ee4ae8038e6693398
    Generated by bug-report-triage (ID: bug-report-triage_6acf1b6816c2a7.30999270)

  12. pirate-bot commented on Oct 16, 2026

    @pirate-bot
    pirate-bot
    on Oct 16, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again (fingerprint 4bdf9838a53fa6e44795fe709a1380fd): 91 occurrence(s) across 1 site(s), last seen 2026-10-15 12:47 UTC.
    Automated crash telemetry captured this again (fingerprint 69c13bf2b1d893d2a6aa908061264859): 88 occurrence(s) across 2 site(s), last seen 2026-10-14 07:53 UTC.
    Automated crash telemetry captured this again (fingerprint 20a9aad8074c675bc9a009ce936688e0): 42 occurrence(s) across 3 site(s), last seen 2026-10-16 01:01 UTC.

    Customers on older Neve releases (v3.7.5, v3.8.4, and v4.0.1) experience a PHP fatal error during REST requests when optional classes like \Neve\Abilities\Loader are looked up but their corresponding files are absent. The root cause is located in Neve\Autoloader::require_file() within autoloader.php, which unconditionally executes require on mapped candidates without checking file existence. This defect is tracked in open issue #4605 and was resolved in later versions by adding file availability checks.

    Source: automated crash report — neve, fingerprints 4bdf9838a53fa6e44795fe709a1380fd, 69c13bf2b1d893d2a6aa908061264859, 20a9aad8074c675bc9a009ce936688e0
    Generated by bug-report-triage (ID: bug-report-triage_6ad1be12cbbe82.19243744)

  13. pirate-bot commented on Oct 18, 2026

    @pirate-bot
    pirate-bot
    on Oct 18, 2026
    CollaboratorAuthor

    Automated crash telemetry captured this again (fingerprint 83ff9482e08e63520b74ba282df92213): 12 occurrence(s) across 1 site(s), last seen 2026-10-18 04:03 UTC.
    Automated crash telemetry captured this again (fingerprint 521b1bb400f2b7f1f733e1fa40f0d3ac): 11 occurrence(s) across 1 site(s), last seen 2026-10-18 04:25 UTC.

    Customers experience an uncaught fatal error during REST requests when Neve Pro probes for theme abilities and the autoloader unconditionally requires a mapped file that does not exist. The root cause is located in Neve\Autoloader::require_file(), which executes an unguarded require on the candidate path, coupled with the fact that inc/abilities/loader.php is absent from Neve v3.8.11 and v3.8.16. This behavior is tracked in open issue #4605, and the missing file guard has since been resolved in v4.2.11 and later.

    Source: automated crash report — neve, fingerprints 83ff9482e08e63520b74ba282df92213, 521b1bb400f2b7f1f733e1fa40f0d3ac
    Generated by bug-report-triage (ID: bug-report-triage_6ad460f419df86.62179626)

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

Metadata

Metadata

Assignees

Labels

bug-reportbug-report-triagecrash-report

Type

Bug

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions