The 5 things that actually break in a Moodle 5.1 5.2 upgrade

Moodle 5.2 upgrades often fail due to five specific issues. Before attempting a database-level fix, check these common causes:

1. The web root must point to the 'public' directory. Since Moodle 5.1, web-accessible code resides under public/. A misconfigured vhost pointing to the parent directory can cause 404 errors, security check failures, and other strange issues. Adjust the DocumentRoot directive or use a symlink or location alias if you're on cPanel or shared hosting. If your host lacks support, that's a hosting limitation, not a Moodle issue.

2. The router must forward requests to r.php. Moodle 5.1+ routes non-file requests through r.php. If this isn't configured correctly, you'll encounter 404s, missing assets, and router errors in the environment check. Make sure FallbackResource is set to /r.php and try_files $uri $uri / /r.php $is_args$args. Occasionally, PHP-FPM may handle the missing path before Apache can fall back to r.php, requiring separate debugging.

3. Composer dependencies must be present. Moodle 5.1+ requires a vendor/ directory. If missing, Composer errors will appear during startup. Run composer install --no-dev --classmap-authoritative from the Moodle root, not public. If you don't have shell access, build the release elsewhere and upload the complete codebase, including vendor/, to the server.

4. A plugin might still use old class names. For instance, a Class Mustache_Engine not found error indicates that an outdated plugin or theme is calling the older class name. After a core upgrade, this could happen if the plugin isn't compatible with Moodle 5.2. Update or remove the problematic plugin on a staging site and ensure compatibility with the upgraded Moodle version. Avoid relying on a clean file copy as proof of plugin compatibility; verify each non-core plugin against your target Moodle version.

5. Caches must be cleared after a clean upgrade. Many "this feature is broken" reports are simply due to stale caches. Examples include the file picker refusing to load. Run php admin/cli/upgrade.php followed by php admin/tool/purgesitesup/clear-all-caches. For production environments, use the CLI to bypass potential browser, proxy, and timeout issues with the web upgrader on larger sites.

By checking these five factors first, many Moodle 5.2 upgrade problems become more manageable. Always back up your code, moodledata, and database before upgrading, and test the upgrade on a copy of your site before implementing changes in production. For a comprehensive guide, including server requirements, clean code replacement process, symptom-to-cause table, and rollback guidance, refer to the Moodle 5.1 to 5.2 Upgrade Guide.