DEV Community

Cover image for The 5 things that actually break in a Moodle 5.1 5.2 upgrade
Choaib Mouhrach
Choaib Mouhrach

Posted on

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

#moodle #php #webdev #devops

Every "mysterious" Moodle 5.2 upgrade failure I've debugged has come down to the same five things.

Not ten, not fifty. Five.

If your site broke after upgrading from 5.1, check these before you start touching the database.

1. The web root isn't pointing at public

This is one of the most common causes of Moodle 5.x upgrade problems. Since Moodle 5.1, the web-accessible code lives under public/. If your vhost is still pointing to the parent directory, you'll get 404s, failed security checks, and other weird errors.


DocumentRoot /var/www/moodle/public
Enter fullscreen mode Exit fullscreen mode 

root /var/www/moodle/public;
Enter fullscreen mode Exit fullscreen mode

If you're on cPanel or shared hosting and can't edit the vhost, you'll need a configurable docroot, a symlink, or a location alias. If your host doesn't support any of those, that's a hosting limitation, not a Moodle problem.

2. The router isn't forwarding requests to r.php

Moodle 5.1+ sends non-file requests through r.php. If that's not configured properly, you'll see 404s, missing assets, and router errors in the environment check.


FallbackResource /r.php
Enter fullscreen mode Exit fullscreen mode 

try_files $uri $uri/ /r.php$is_args$args;
Enter fullscreen mode Exit fullscreen mode

One thing that can be confusing here: if a .php-looking route returns a 404 instead of a 302, PHP-FPM may be handling the missing path before Apache gets a chance to fall back to r.php. That's a separate issue and needs to be debugged on its own.

3. Composer dependencies are missing

Moodle 5.1+ expects the vendor/ directory to be there. If it's missing, you'll get Composer errors during startup.

From the Moodle root, not public, run:


composer install --no-dev --classmap-authoritative
Enter fullscreen mode Exit fullscreen mode

No shell access? Build the release somewhere else and upload the complete Moodle codebase, including vendor/.

4. A plugin is still using old class names

A classic example is:


Class "Mustache_Engine" not found
Enter fullscreen mode Exit fullscreen mode

If you get this after an otherwise successful core upgrade, it's not necessarily a database problem. Moodle 5.2 uses namespaced Mustache classes, so an older plugin or theme that still calls the old class name can break the site.

Update or remove the offending plugin on staging and make sure you're using a release that actually supports Moodle 5.2.

Also, don't take a clean file copy as proof that a plugin is compatible. Check every non-core plugin against the Moodle version you're upgrading to.

5. Caches weren't properly cleared

After a clean upgrade, a lot of "this feature is broken" reports are just stale caches.

The file picker refusing to load is a good example.

Run:


php admin/cli/upgrade.php
Enter fullscreen mode Exit fullscreen mode

Then go to Site administration > Development > Purge all caches.

On production, I'd use the CLI where possible. It avoids the browser, proxy, and timeout issues you can run into with the web upgrader on larger sites.

Check these five things first and a lot of Moodle 5.2 upgrade problems become much easier to track down.

Also, before you upgrade, back up all three:

  1. Code
  2. moodledata
  3. Database

Having a copy of the files alone isn't a rollback plan.

And always test the upgrade on a copy of the site before doing it in production.

I wrote the full step-by-step guide here, including the server requirements, clean code replacement process, a symptom-to-cause table, and when it's time to stop and roll back:

Moodle 5.1 to 5.2 Upgrade Guide

Top comments (0)