This guide explains how to use Discourse’s Safe Mode to troubleshoot issues with themes and plugins.
Required user level: All users
Discourse offers a “JavaScript Safe Mode” that allows any user to isolate the root cause of JavaScript issues caused by plugins, themes, or theme components. This feature is particularly useful for troubleshooting problems on your Discourse site.
Accessing Safe Mode
To access Safe Mode, follow these steps:
-
Open a new browser tab.
-
Enter the following URL in the address bar, replacing
[your-site-name](http://discourse.example.com)with your actual Discourse site domain:http://discourse.example.com/safe-modeFor example, the Safe Mode URL for the Discourse demo site is:
https://try.discourse.org/safe-mode -
Click the ‘Enter Safe Mode’ button:
Safe Mode options
When entering Safe Mode, you can select from the following options:
- Disable themes and theme components
- Disable unofficial client-side plugin customizations
- Disable all client-side plugin customizations
- Make Javascript deprecations raise an error
By default, the first three options are selected. The deprecation errors option is unchecked by default, and is primarily useful for plugin and theme developers testing compatibility with upcoming Discourse updates. You can enter Safe Mode multiple times with different combinations to isolate the specific component causing issues on your site.
Using Safe Mode
- Select the desired options on the Safe Mode page.
- Click “Enter Safe Mode” to apply your selections.
- You will see a banner indicating that Safe Mode is enabled.
- Browse your site to check if the issue persists with the selected components disabled.
Exiting Safe Mode
To exit Safe Mode, simply close your browser tab.
Important notes
When sharing a Safe Mode link for your site, be aware that it needs to be opened in a new tab or added directly to the address bar; otherwise, it may not work correctly.
Safe Mode currently only disables the JavaScript portions of plugins. To disable the server-side portion of a plugin, you must rebuild your container with the plugin commented out.
Troubleshooting
If you cannot load the initial Safe Mode selection page, try visiting the following URL, which will skip the page and load Safe Mode directly:
https://discourse.example.com/?safe_mode=no_themes,no_plugins
For example: https://try.discourse.org/?safe_mode=no_themes,no_plugins
The available safe_mode query parameter values are: no_themes, no_unofficial_plugins, no_plugins, and deprecation_errors. These can be combined with commas.
Last edited by @hugh 2024-07-30T05:32:08Z
Check document
Perform check on document:
