Frontend initialization fatals when `Options_Settings` is unavailable in the autoloader

Summary

Otter Blocks can terminate frontend WordPress initialization with Class ".../Options_Settings" not found.

Expected behavior: frontend requests initialize Otter Blocks without a fatal error.

Actual behavior: initialization stops while loading the Options Settings component.

Impact: affected frontend requests render as a fatal error instead of serving the page.

Customer context

• Product / area: Otter Blocks frontend initialization
• Version: 3.2.1
• Environment: WordPress 7.0.2, PHP 8.4.23
• Integration / third party: Themeisle SDK 3.3.58 was reported, but the crash location is outside SDK code.
• Reported error / symptom: Class ".../Options_Settings" not found at inc/class-main.php:97
• Impact: 2 occurrences across 1 production site during the reported window.

Reproduction notes

1. Install Otter Blocks 3.2.1 in an environment where the Composer autoloader cannot resolve ThemeIsle\GutenbergBlocks\Plugins\Options_Settings.
2. Load a frontend request so Otter Blocks reaches its init bootstrap.
3. Observed in telemetry: WordPress terminates with Class ".../Options_Settings" not found at inc/class-main.php:97.

A clean reproduction using the published 3.2.1 archive has not been performed; the reported site’s deployed files are unavailable.

Diagnosis

Conclusion

Production telemetry confirms a frontend fatal at the class-instantiation branch in Otter Blocks 3.2.1. The tagged source declares the requested Options_Settings class, so the observed missing-class error indicates that the runtime autoloader artifact did not resolve a class the product bootstraps. The release build ordering provides a plausible product-owned artifact path: the distributable is copied before Composer dependencies are installed or refreshed.

Where this likely occurs

• inc/class-main.php — Main::autoload_classes() lines 66-97 lists \ThemeIsle\GutenbergBlocks\Plugins\Options_Settings at line 78 and unconditionally instantiates each listed class at line 97. This is the reported crash location and runs from the init hook registered by Main::init() at line 36.
• inc/plugins/class-options-settings.php — ThemeIsle\GutenbergBlocks\Plugins\Options_Settings lines 8-16 declares the namespace and class expected by the failing bootstrap entry.
• composer.json — autoload lines 61-65 classmaps inc/, establishing that this class is intended to be resolved through Composer-generated autoload metadata.
• bin/dist.sh — distribution workflow lines 26-32 copies the source tree into dist/ with rsync before running Composer installation commands in the source working directory. The inspected .distignore does not exclude vendor (.distignore lines 20-46), so a copied dependency directory can reflect its state before those commands.
• Tag v3.2.1 at commit 059432d330bbd5ce54ad9402953ecb6189498e9e contains the same bootstrap list and Composer classmap configuration. History shows the class and bootstrap entry existed before v3.1.10; no source rename/removal regression was found between v3.1.10, v3.2.0, and v3.2.1.

Engineering notes

The visible failure is limited to a production site report on version 3.2.1 and does not establish how broadly a release artifact is affected. The direct source declaration and the expected Composer classmap coexist, whereas runtime class resolution failed. This is consistent with incomplete, stale, or mixed autoload metadata in a shipped or deployed package; the inspected repository does not contain the released ZIP or its generated vendor/composer files, so the exact artifact state remains unverified.

Test coverage status

tests/test-options-settings.php directly imports and constructs Options_Settings in Test_Options_Settings::set_up() at lines 8 and 22-26. No relevant packaged-artifact, distribution, or Composer classmap validation coverage was found during inspection. The existing unit test does not exercise the frontend bootstrap loop or a generated release package.

What to verify or explore next

• Reproduce from the released 3.2.1 ZIP on a clean WordPress installation and inspect whether its Composer autoload metadata maps Options_Settings.
• Compare a freshly generated distribution artifact with the published 3.2.1 package, including the vendor/composer contents.
• Run the frontend bootstrap path with the packaged dependencies rather than the development checkout.
• Check whether the reported site had a mixed plugin directory or opcode cache state at the time of the fatal.

Unknowns / follow-up

• The published 3.2.1 archive was not available in the workspace, so the failed site's exact classmap cannot be compared with it.
• Telemetry contains no structured stack trace beyond the shutdown-detected fatal and no deployment history for the affected site.

Confidence

Confidence: 82/100

Production telemetry captured the fatal twice on one site running Otter Blocks 3.2.1. The tagged source declares Options_Settings and instantiates it during every frontend initialization, while the distribution workflow copies package contents before refreshing Composer dependencies, creating a credible release-artifact path for a stale or incomplete classmap.

Crash telemetry

Occurrences	2
Distinct sites	1
First seen	2026-08-02 21:03 UTC
Last seen	2026-08-03 14:50 UTC
Crash location	product:inc/class-main.php:97
Request context	frontend
Inside Themeisle SDK	no
Product versions	3.2.1
WP versions	7.0.2
PHP versions	8.4.23
SDK versions	3.3.58

---

Source: automated crash report — otter-blocks, fingerprint 935ebf7c52cd3db256e4843f2fcb9ba2
Generated by bug-report-triage (ID: bug-report-triage_6a717ffb9362d9.50796986)

Start with inc/class-main.php and inc/plugins/class-options-settings.php to trace the frontend bootstrap, then inspect composer.json and bin/dist.sh for classmap and distribution ordering. Reproduce from the released 3.2.1 ZIP or a matching package and compare vendor/composer metadata with a freshly generated artifact. Done means the packaged frontend bootstrap resolves Options_Settings without a fatal and the artifact path is validated.