Frontend fatal when `Registration` is unavailable during startup

Summary

Otter Blocks can terminate a frontend request during plugin startup when the Registration class is unavailable to the autoloader.

Expected behavior: A missing or unavailable startup class does not bring down the request; unavailable functionality is skipped or otherwise handled safely.

Actual behavior: Startup throws an uncaught "Class .../Registration not found" error during init.

Impact: The affected site cannot serve the frontend request while this startup condition is present.

Customer context

• Product / area: Otter Blocks startup autoloader
• Version: 3.2.2
• Environment: WordPress 7.0.4; PHP 8.4.23 and 8.4.24
• Integration / third party: Themeisle SDK 3.3.59 reported; crash location is not inside SDK code
• Reported error / symptom: Uncaught Class .../Registration not found fatal at inc/class-main.php:97 during frontend init
• Impact: 2 occurrences across 2 production sites in the telemetry query window

Reproduction notes

1. Use Otter Blocks 3.2.2.
2. Arrange for the autoloader to be unable to resolve ThemeIsle\GutenbergBlocks\Registration while the plugin remains active. The exact production condition is unknown.
3. Load a frontend request that reaches WordPress init.

Reported result: An uncaught missing-class fatal is thrown at startup. Repository confirmation: the tagged startup loop instantiates this class without first checking loadability.

Diagnosis

Conclusion

Production telemetry records an uncaught missing-Registration class error at the startup instantiation line. In the 3.2.2 tagged source, Main::autoload_classes() places Registration first in its startup list and directly instantiates every filtered entry without checking whether the class is loadable. This is sufficient to produce the reported fatal when a deployed artifact or autoload mapping cannot provide that class.

Where this likely occurs

• inc/class-main.php — Main::init() lines 31-40 registers Main::autoload_classes() on WordPress init.
• inc/class-main.php — Main::autoload_classes() lines 63-102 lists \ThemeIsle\GutenbergBlocks\Registration at line 67 and instantiates each entry at line 97 without a loadability check.
• otter-blocks.php — plugin bootstrap lines 35-42 conditionally loads vendor/autoload.php before creating Main.
• composer.json — autoload lines 61-65 classmaps inc/, the directory containing Registration.
• v3.2.2 is commit 27858f6e and retains the unguarded path. Commit 69e64b52 (fix: frontend fatal when a listed class cannot be autoloaded) adds a guarded startup-class path and focused tests, but no local release tag contains it.

Engineering notes

• The inspected source contains Registration in inc/class-registration.php lines 17-19. The telemetry therefore indicates the class was unavailable at runtime rather than absent from the repository source.
• A stale or incomplete Composer classmap/package is an inference supported by the bootstrap and classmap configuration; the crash report does not identify the deployment condition that made Registration unavailable.
• The public otter_blocks_autoloader filter at inc/class-main.php:94 can also alter the startup list. The recorded failure concerns the built-in Registration entry, not a verified third-party filter modification.
• The report concerns the free plugin repository. The crash location is explicitly outside the bundled Themeisle SDK.

Test coverage status

tests/test-registration.php lines 177-245 tests unavailable dynamic block renderer classes inside Registration::register_blocks(), whose guarded renderer branch is at inc/class-registration.php lines 971-987. Those tests do not exercise Main::autoload_classes() or an unavailable Registration startup entry. Commit 69e64b52 introduces tests/test-main-autoload.php, including unavailable startup-class coverage and verification that listed bundled classes are loadable; that test file is not in v3.2.2.

What to verify or explore next

• Reproduce with a 3.2.2 package whose autoloader cannot resolve ThemeIsle\GutenbergBlocks\Registration, then request a frontend route.
• Compare the affected release archive's Composer autoload metadata and inc/class-registration.php against the source tag.
• Run the startup-autoloader coverage introduced by 69e64b52 against the release packaging workflow.
• Verify whether the production cases had plugin-update interruption, partial deployment, or another classmap-altering condition.

Unknowns / follow-up

• The telemetry intentionally redacts the complete runtime class path and contains no structured stack trace beyond the shutdown-detected fatal.
• No affected site filesystem, plugin archive, or autoload metadata was available for inspection, so the condition that made the source-present class unavailable remains unverified.

Confidence

Confidence: 96/100

Production telemetry records a frontend fatal in Otter Blocks 3.2.2 at the unguarded startup instantiation path. The tagged source contains that path, and an unreleased targeted commit adds coverage and a loadability guard for this precise failure mode.

Crash telemetry

Occurrences	2
Distinct sites	2
First seen	2026-08-12 19:21 UTC
Last seen	2026-08-12 20:25 UTC
Crash location	product:inc/class-main.php:97
Request context	frontend
Inside Themeisle SDK	no
Product versions	3.2.2
WP versions	7.0.4
PHP versions	8.4.23, 8.4.24
SDK versions	3.3.59

---

Source: automated crash report — otter-blocks, fingerprint 6fb663f46491443dc5b81f0d9a5363a1
Generated by bug-report-triage (ID: bug-report-triage_6a7d5d85c59000.36461702)

Start in inc/class-main.php, especially Main::autoload_classes(), and compare its startup path with the focused coverage in tests/test-main-autoload.php from commit 69e64b52. Run the startup-autoloader tests against the 3.2.2 packaging path. Done means an unavailable listed startup class does not cause a frontend fatal and the relevant bundled-class coverage passes.