DEV Community: Choaib Mouhrach

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

Choaib Mouhrach — Wed, 23 Sep 2026 22:20:15 +0000

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


root /var/www/moodle/public;

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


try_files $uri $uri/ /r.php$is_args$args;

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

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

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

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:

Code
moodledata
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

Navigating Email Scheduling: Tackling Every Hurdle

Choaib Mouhrach — Thu, 21 Mar 2024 03:06:07 +0000

Introduction:

Following the seamless transition from QSTASH to a VPS, and with the application running smoothly, I received referrals from a satisfied client to three more potential clients. They expressed interest in having the same application with additional features.

Background:

This led me to launch three new containers, each with its subdomain for every client and interconnected via Caddy. However, this process unearthed more challenges than expected, particularly regarding resource allocation.

Challenges:

Cumbersome Email Scheduling:

Upon consulting with the new clients, I discovered they desired the ability to specify both the hour and minute for their emails. However, after delving deeper into their needs, I realized they sought to send emails at regular intervals. This prompted a revamp of the scheduling mechanism, transitioning from setting numerous timestamps to simply specifying a custom duration for email dispatch. This optimization not only streamlined the cron jobs but also enhanced performance and user experience.

Resource Management:

Each container operated its own Postgres database and cron jobs, resulting in redundant resource consumption. To address this, I transformed the system into a multi-user setup with a single container and a shared database, akin to modern SaaS applications. This consolidation significantly reduced resource wastage and improved cron scheduling efficiency.

Tailored Features for Each Client:

The transition to a SaaS-like architecture not only resolved resource inefficiencies but also simplified feature deployment. Instead of creating separate branches and custom code for individual clients, I adopted a unified approach, allowing simultaneous updates across all containers. This streamlined deployment procedures and enhanced agility in feature delivery.

Automation and Deployment Pain Points:

The manual update process, involving container shutdowns, code pulls, image rebuilding, and container restarts, proved laborious and prone to downtime. Recognizing the need for automation, I introduced Jenkins into the workflow. By configuring Jenkins to automate deployment tasks, such as pulling code changes and rebuilding containers, I alleviated deployment pains and enabled seamless feature integration.

Addressing Next.js Caching Challenges:

Next.js caching limitations posed a significant hurdle, particularly in a multi-client environment where data consistency was paramount. Transitioning to a SaaS architecture necessitated a shift in caching strategies, opting for client-side fetching with React Query to mitigate caching issues effectively.

Mitigating Gmail SMTP Constraints:

Utilizing Gmail SMTP for email dispatch posed significant challenges due to the imposed daily email quotas. Understanding the critical need for reliable email delivery while staying within these constraints, I engaged in extensive discussions with clients to devise a sustainable solution.

Collaboratively, we strategized to optimize email dispatch schedules, ensuring emails were sent efficiently while adhering to Gmail's limitations. After thorough deliberation, we agreed to truncate the 24-hour email dispatch window to a more manageable 9 hours, spanning from 7 AM to 4 PM.

Calculating the optimal email frequency within this timeframe, we settled on a duration of 3 minutes between each email dispatch. This meticulous planning ensured that the total number of emails sent per day per account remained well within Gmail's prescribed limits.

By implementing this refined scheduling strategy, clients were assured of uninterrupted email delivery to both their internal addresses for verification purposes and their target recipients. This collaborative approach not only addressed the immediate constraint posed by Gmail SMTP limitations but also fostered a deeper understanding of client needs and expectations.

Resolving Next.js Instrumentation and Cron Job Issues:

Technical glitches with Next.js instrumentation and cron job management necessitated a shift in approach. By decoupling cron-related functionalities from Next.js and implementing a separate Express.js server, I successfully resolved these issues and ensured reliable cron job scheduling.

Optimizing for Efficiency and Scalability:

Further optimizations included migrating the application from VPS to Vercel for cost efficiency and scalability, as well as transitioning the database to Neon DB for enhanced affordability.

Conclusion:

Through iterative problem-solving and adaptation, I successfully overcame various challenges in email scheduling, culminating in a robust and efficient solution. This journey underscores the importance of flexibility, automation, and client collaboration in delivering effective software solutions.