Bugs: stable Docker image regression: LMS app missing after Frappe v15→v16 upgrade, no migration path

[EvilAmir]

---

First of all

Thank you for building and maintaining Frappe LMS — it's a great project and we really appreciate the work that goes into it. We're running it in production and love the platform.

---

Summary

After running easy-install.py upgrade, the ghcr.io/frappe/lms:stable image was updated from Frappe v15 to Frappe v16.17.0. Unfortunately this caused a complete service outage for our production installation. We'd like to share the full failure chain in hopes it helps improve the upgrade process.

---

Environment

• Deploy method: easy-install.py
• OS: Ubuntu 24.04
• Previous working state: Frappe 15.101.0, LMS 2.45.1, Python 3.11
• State after update: Frappe 16.17.0, Python 3.14

---

Issue 1: stable image does not include the LMS app

After pulling the new stable image, the LMS app is absent from the bench:

$ docker exec backend ls /home/frappe/frappe-bench/apps/
frappe
# lms is not present

Running bench migrate immediately fails:

ModuleNotFoundError: No module named 'lms'

It seems the new image may have been published without the LMS app bundled, which makes it unusable for LMS deployments out of the box.

---

Issue 2: Manual LMS installation requires payments — undocumented dependency

Following the natural workaround of manually installing LMS via bench get-app lms fails at the install step:

$ bench --site lms.example.com install-app lms
An error occurred while installing lms: No module named 'payments'

The current LMS branch requires payments as a dependency. This dependency:

• Does not appear to be documented in the installation guide
• Was not required in v15
• Is not included in the stable image

It would be helpful to either include payments in the image or document it as a required step.

---

Issue 3: easy-install.py upgrade has no major version compatibility check

The upgrade script currently:

1. Pulls the new image
2. Immediately runs bench --site all migrate
3. Does not check for Frappe major version compatibility beforehand

By the time the incompatibility error appears, the database has already been partially modified, making a clean rollback difficult. A simple version check before migration would prevent this situation entirely.

---

Issue 4: Database becomes inconsistent after failed upgrade + rollback

When attempting to install payments as a workaround for Issue 2, it partially modifies the database:

-- payments added to installed_apps in tabDefaultValue
["frappe", "lms", "payments"]

-- Records created in tabInstalled Application
payments | 0.0.1

-- Records created in tabModule Def
Payment Gateways | payments
Payments         | payments

After rolling back to the cached v15 image, bench migrate continues to fail because v15 does not have payments, but the database now expects it.

We were able to recover by manually cleaning up these records:

UPDATE `tabDefaultValue` 
SET defvalue='["frappe", "lms"]' 
WHERE defkey='installed_apps';

DELETE FROM `tabInstalled Application` WHERE app_name='payments';
DELETE FROM `tabModule Def` WHERE app_name='payments';

It would be great if the upgrade script could handle this kind of rollback automatically, or at least document the recovery steps.

---

Issue 5: No versioned image tags for major Frappe versions

The stable tag currently moves between major Frappe versions (v15 → v16) without any announcement or warning. Having versioned tags like stable-v15 or stable-v16 would allow users to control when they migrate between major versions and follow a proper migration guide before doing so.

---

Suggestions

We understand this is a complex project to maintain. A few things that would significantly improve the upgrade experience:

• Ensure the stable image always includes a working LMS installation
• Consider versioned tags (stable-v15, stable-v16) for major version control
• Add a Frappe major version compatibility check to easy-install.py upgrade before running migrations
• Publish a v15 → v16 migration guide when the stable tag moves to v16
• Document payments as a dependency if it's now required

[iamrubeng]

This commit is the reason: frappe/frappe_docker@ae275df

[EvilAmir]

This commit is the reason: frappe/frappe_docker@ae275df

Thank you for the pointer! Looking at commit ae275df, it seems the build pipeline change (replacing APPS_JSON_BASE64 with BuildKit secret mount) may have caused the stable image to be published without the LMS app bundled. The image appears to have been built without the secret being passed correctly, resulting in an empty bench with only frappe installed.
Could the maintainers confirm whether the ghcr.io/frappe/lms:stable image CI/CD pipeline has been updated to pass the apps.json secret correctly after this change? It would explain why the image is missing the LMS app entirely.

[emilyastranova]

Confirming I am also dealing with this issue

[emilyastranova]

This fix doesn't even work for me on a brand new install. The LMS still has an issue where its saying its missing "payments" but installing/force installing it and restarting doesn't fix anything. The LMS just 404s. The LMS Courses works fine. As a brand new user, I cannot currently roll out Frappe LMS at all, especially since the version-15 branch no longer exists :/