Upgrade on Lessons learned

Moodle 5.3 Classic theme serves an empty stylesheet: 'Undefined variable $mds-spacing-md'

Sat, 24 Oct 2026 14:58:00 +0200

After an upgrade to Moodle 5.3, every page on the Classic theme lost its layout. The theme’s stylesheet came back like this:

$ curl -s -o /dev/null -w '%{http_code} %{size_download}\n' \
 'https://moodle.example.com/theme/styles_debug.php?theme=classic&type=scss'
200 0

That’s a 200 with an empty body, and nothing in the logs. With debugging forced to developer level, the SCSS compiler said:

Error while compiling SCSS: Undefined variable $mds-spacing-md: /opt/moodle/public/theme/classic/scss/../../boost/scss/moodle/course.scss on line 132, at column 17

Classic imports Boost’s SCSS, and in 5.3 that SCSS uses the new design system’s tokens. Classic never imports them. One @import fixes it.

The setup

Moodle 5.3.0, PHP 8.4.27, in a Docker image of our own, upgraded from 5.0
The site’s theme is Classic. It left core in 5.3, so the image installs it from moodlehq/moodle-theme_classic (at commit 363a179, the only one when I checked)
Theme designer mode was on, so pages loaded the theme through styles_debug.php

I rehearsed the upgrade on a copy of the production database. Every URL I tried returned 200, and admin/cli/checks.php reported all checks OK. On production, the pages had no layout.

Two things that looked like the cause

The browser console had two errors:

[Error] Failed to load resource: the server responded with a status of 404 (Not Found) (client.bundle.js.map, line 0)
[Error] Failed to load resource: the server responded with a status of 404 (Not Found) (react.bundle.mjs.map, line 0)

Those are source maps. The browser asks for them only for its developer tools, and Moodle doesn’t ship them. They don’t affect the layout.

The import map had a few 404s as well, for entries like /core/esm/<rev>/bootstrap/. Those entries end in a slash because they map a whole prefix, so the bare URL has nothing to serve. The modules under them loaded.

The problem showed up when I fetched every stylesheet the front page links to and printed its size:

curl -s https://moodle.example.com/ -o index.html
grep -oE '<link[^>]+stylesheet[^>]*>' index.html \
 | grep -oE 'href="[^"]+"' | sed 's/href="//; s/"$//; s/&amp;/\&/g' \
 | while read -r u; do
 printf '%s %s\n' "$(curl -s "$u" | wc -c)" "$u"
 done

The plugin stylesheets had a few kilobytes each. The theme’s own, type=scss, had zero bytes.

Getting the real error

Moodle catches the compiler’s exception and passes the message to debugging() at developer level, so at the usual debug setting you get nothing at all. You don’t have to change the site’s settings to see it. Compile the theme from the CLI with debugging switched on for that one process (run it as the web server’s user and adjust the path to config.php):

sudo -u www-data php -r '
define("CLI_SCRIPT", 1);
require "/opt/moodle/config.php";
$CFG->debug = E_ALL;
$CFG->debugdisplay = 1;
$t = \core\output\theme_config::load("classic");
$m = new ReflectionMethod($t, "get_css_content_from_scss");
$c = $m->invoke($t, false);
var_dump(is_string($c) ? strlen($c) : $c);
'

get_css_content_from_scss isn’t public, hence the reflection. It returns false when the compile fails, and the error comes with the import chain:

++ Error while compiling SCSS: Undefined variable $mds-spacing-md: /opt/moodle/public/theme/classic/scss/../../boost/scss/moodle/course.scss on line 132, at column 17
Call Stack:
#0 import /opt/moodle/public/theme/classic/scss/../../boost/scss/moodle/course.scss /opt/moodle/public/theme/classic/scss/../../boost/scss/moodle.scss on line 13
#1 import /opt/moodle/public/theme/classic/scss/../../boost/scss/moodle.scss /opt/moodle/public/theme/classic/scss/moodle.scss on line 2
#2 import /opt/moodle/public/theme/classic/scss/moodle.scss (unknown file) on line 127 ++

Why

Boost’s default preset, theme/boost/scss/preset/default.scss, starts with:

// Import Moodle Design System tokens.
// Must be imported before Bootstrap so that the design system tokens can be used to override Bootstrap variables.
@import "design-system";

design-system.scss pulls in the $mds-* tokens. Classic’s presets import fontawesome, bootstrap and moodle, but not design-system, and Classic’s moodle.scss imports Boost’s. So Boost’s course.scss uses $mds-spacing-md, and nothing has defined it.

The fix

Add the import to the top of theme/classic/scss/classic/pre.scss. Classic’s lib.php puts that file in front of the preset, so this covers both presets:

pre=/opt/moodle/public/theme/classic/scss/classic/pre.scss
{ printf '@import "../../boost/scss/design-system";\n\n'; cat "$pre"; } > /tmp/pre.scss
mv /tmp/pre.scss "$pre"
sudo -u www-data php /opt/moodle/admin/cli/purge_caches.php --theme

The path resolves from theme/classic/scss/, as the call stack above shows. After the purge, the same CLI compile returned 1,218,070 characters instead of false, and styles_debug.php sent 1,557,703 bytes.

If Classic is part of your build, as here, apply the patch in the build. A fix made inside a running container is gone the next time the container is recreated.

Once the layout was back, I turned theme designer mode off (admin/cli/cfg.php --name=themedesignermode --set=0). It recompiles the theme on every page view: here, about 0.8 s and 112 stylesheet requests per page.

Takeaway

A Moodle theme that fails to compile still answers 200, just with no CSS, so upgrade checks that look only at status codes pass right over it.

Before your next Moodle upgrade, add the theme’s compiled CSS size to your checklist: anything near zero is a failed compile.

Uninstalling one Odoo module can remove its dependents and their data

Sun, 30 Aug 2026 00:00:00 +0000

An Odoo module replacement passed a rehearsal’s record-count and accounting-total checks, yet the uninstall also removed a dependent addon that owned important business data. The application still loaded. The acceptance checks had missed the field that mattered.

Before replacing a module, inspect its reverse dependencies and data ownership. Rehearse the corrected transition on a restored copy, then compare the affected values by record identity before approving the live change.

Uninstall computes a reverse-dependency set

In Odoo 18’s module implementation , downstream_dependencies() recursively finds modules that depend on the selected modules. button_uninstall() marks both the selection and those dependents as to remove.

The same source describes module_uninstall() as removing database structures created by the module, including tables and columns. Actual deletion depends on the affected records and metadata; do not assume every business record disappears, or that surviving rows retain every field.

Generalize the replacement to a full addon, a smaller replacement, and an extension that depends on the full addon. Installing the smaller addon does not automatically redirect the extension’s dependency. Uninstalling the full addon still includes that extension in the removal set.

The first rehearsal had the wrong acceptance criteria

The historical transition checked surviving records, aggregate totals, and registry health. Those checks passed while the dependent addon was also uninstalled. The user caught the missing preservation requirement and required a restore.

The subsequent investigation found a second problem: changing the extension’s manifest alone would be insufficient. The smaller replacement did not yet implement a field the extension required. That field’s behavior needed to be ported before changing the dependency.

The retained record includes the corrective restore and a later clone’s uninstall/registry-reload output. It ends with the corrected rehearsal and final verification still open. It does not prove a successful final transition or a completed before/after digest comparison.

Rehearse the field handoff explicitly

A safer transition procedure is:

Quiesce writes and capture a consistent database and filestore backup. Verify checksums and prove that the pair restores.
Record installed module states, reverse dependencies, and the fields and records that must survive. Keep the addon source revisions with the backup.
Implement the required field behavior in the replacement, including compute and reversal behavior where applicable. Version-control the dependent addon too.
On an isolated restore, install the replacement and upgrade the dependent addon so the database’s module metadata reflects the new dependency. Inspect the removal set again before uninstalling the old addon.
Complete the uninstall, reload the registry, and compare the required values and behavior. Investigate field metadata and ownership during the handoff; identical field names alone do not establish safe transfer.

Disable scheduled jobs and outbound integrations on the clone. A rehearsal should not send mail, contact payment services, or write to production storage.

Compare identity and value, not only counts

For a small affected dataset, compare canonical exports directly. For larger exports, a digest is convenient if the query scope, ordering, and serialization remain identical.

This synthetic Python check demonstrates why counts and non-null counts are insufficient. It models two records whose field values were exchanged; it is not an Odoo migration test:

import hashlib
import json


def digest(rows):
 payload = json.dumps(sorted(rows), separators=(",", ":"), ensure_ascii=True)
 return hashlib.sha256(payload.encode("utf-8")).hexdigest()


before = [(1, "2026-01-10"), (2, None), (3, "2026-01-20")]
after = [(1, "2026-01-20"), (2, None), (3, "2026-01-10")]
assert len(before) == len(after)
assert sum(value is not None for _, value in before) == 2
assert sum(value is not None for _, value in after) == 2
assert digest(before) == digest(list(reversed(before)))
assert digest(before) != digest(after)
print("counts match; identity/value digest detects the change")

For a real comparison, export the stable record ID alongside each affected field, preserve nulls, and normalize dates and other types explicitly. A missing column must fail the check. Also test compute behavior and important workflows: a value digest cannot prove those work.

Before your next uninstall, list which dependent addons and field values must remain, and make their survival a rehearsal acceptance criterion.