Mattermost Web App Hangs on the Loading Screen After Upgrade Due to an Outdated Playbooks Plugin

Applies to: Mattermost Server v11.0 or later, with one or more plugins running an older build than the version that ships with the server (commonly when MM_PLUGINSETTINGS_AUTOMATICPREPACKAGEDPLUGINS is set to false)

Symptoms: The web app never finishes loading in the browser, while the desktop app may still work, and the server logs show no clear error.

🛑 Problem

Mattermost plugins do not bundle certain shared libraries; instead, the web app provides them to plugins at runtime. As of Mattermost v11.0, the web app no longer provides the StyledComponents (styled-components) library to plugins. Any plugin build that was compiled before v11.0 and still expects that library will fail to load on a v11.0+ web app. When the plugin bundle is evaluated in the browser it throws "Uncaught ReferenceError: StyledComponents is not defined" before it finishes registering. Because the web app waits for each enabled plugin to finish loading, one plugin that never finishes leaves the page loading indefinitely, and the page never becomes usable.

Other plugins that do not depend on the removed library continue to load normally, so only the affected plugin appears to fail. The server itself is healthy, which is why the server logs show no error: the failure happens in the browser while loading the plugin's web app bundle.

A common reason an outdated plugin build is still present is that MM_PLUGINSETTINGS_AUTOMATICPREPACKAGEDPLUGINS is set to false. This tells the server not to install the plugin versions that ship with the current server release and to keep whatever plugin builds are already on disk, so a plugin can remain on a pre-v11.0 build after the server has been upgraded to v11.0 or later.

Symptoms

Loading plugin <plugin-name>, version <old-version>
Uncaught ReferenceError: StyledComponents is not defined

• The web app page keeps loading and never becomes usable in the browser.
• The Mattermost desktop app may still work, because it can be serving older cached files; the problem typically appears first in the web browser.
• The server process starts and runs normally, and the server logs show no clear error.
• Only the plugin named in the browser console error fails to load; other plugins load correctly.

Confirming the cause

Open the browser developer tools and check the Console tab. A plugin that logs "Loading plugin ..." but never logs a matching "Loaded plugin ..." line, followed by "Uncaught ReferenceError: StyledComponents is not defined", is the plugin that needs to be updated.

✅ Solution

The issue is resolved once the affected plugin is updated to a build compatible with the current server version. Use the recommended fix if automatic prepackaged plugins can be re-enabled; otherwise use the alternative.

Recommended fix: let the server install the matching plugin builds

1. Remove MM_PLUGINSETTINGS_AUTOMATICPREPACKAGEDPLUGINS=false, or set it to true.
2. Restart Mattermost. On startup it installs the plugin builds that match the running server version.
3. In the browser, perform a hard refresh or clear the cache so it loads the updated plugin files. The desktop app may also need its cache cleared.

Alternative: keep automatic prepackaged plugins disabled

If MM_PLUGINSETTINGS_AUTOMATICPREPACKAGEDPLUGINS must remain false for the deployment, manually upgrade the affected plugin to the version that ships with your server release, because the older build is not compatible with a v11.0+ web app. You can confirm the version that ships with your server release in the release notes for that version.

⚠️ Important: Re-enabling automatic prepackaged plugins does not re-enable plugins that were intentionally disabled. Enabled and disabled states are controlled separately by MM_PLUGINSETTINGS_PLUGINSTATES, so any plugins you disabled there remain disabled.

Example

On a v11.7.3 server, a deployment with MM_PLUGINSETTINGS_AUTOMATICPREPACKAGEDPLUGINS set to false retained Playbooks v1.41.1, Boards v9.2.2, and Channel Export v1.2.1 from an earlier installation. Playbooks v1.41.1 still depended on the removed StyledComponents library and failed to load, while Boards and Channel Export loaded normally. v11.7.3 is built to ship Playbooks v2.9.1, Boards v9.2.4, and Channel Export v1.3.0; updating Playbooks to the v11.7.3 build resolved the issue.

Additional Resources

Mattermost v11 changelog (the Release v11.0 section documents the StyledComponents change): https://docs.mattermost.com/product-overview/mattermost-v11-changelog.html