Using Safe Mode to troubleshoot issues with themes and plugins

[Discourse]

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:

1. Open a new browser tab.

2. 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-mode
   

   For example, the Safe Mode URL for the Discourse demo site is:
   https://try.discourse.org/safe-mode

3. 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

1. Select the desired options on the Safe Mode page.
2. Click “Enter Safe Mode” to apply your selections.
3. You will see a banner indicating that Safe Mode is enabled.
4. 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:

[Moin]

@sam

Discourse Meta

@sam

Example: Discourse Meta

Somehow, for me those links only work when I open them in a new tab or window. The first one leads to the oops page and the second one to the homepage. But the safe-mode banner does not appear. The second one can lead to problems when you send a link to a user to let them try safe-mode. If they just click the link, they will still use the site without safe-mode.

Maybe this information should be added to the how-to.

[Ed_S]

Good catch -both links are borked. The first needs a ? and the second needs a comma instead of %2C

[Moin]

@Ed_S

The first needs a ?

Where does it need a “?”?
Could you share the link as an example?

[Ed_S]

Oh, sorry, it looks like I’m wrong on the first one: the internal navigation fails, but for a new window it works.
Discourse Meta

And I’m wrong on the other one too! Discourse Meta - The Official Support Forum for Discourse
doesn’t work as a same-page navigation.

My mistake: something is broken, but it’s not the URLs.

[JammyDodger]

I think it’s because it’s trying to open them in place. Rather than argue with it I’ve swopped them out for try.discourse.org.

[Moin]

I think somehow admins should still be informed that sharing those links can easily be a problem.

For example, I report an issue on meta. You could ask, “Could you try https://meta.discourse.org/safe-mode?” Then I would tell you that the link does not work.
Or even worse: you want to specify that I disable only themes, so you ask me to try https://meta.discourse.org/?safe_mode=no_themes. My problem still exists. How are you sure I really used safe-mode? As a user, I think it worked because something happened when I clicked the link.

After I posted here, you know about this. But how do other admins know they have to pay attention that this could be a problem?

[Arkshine]

I’m wondering, due to the nature of this safe home page displayed (that replaces all the content), if an exception should be made to open this link to a new tab.

[JammyDodger]

I’ve added a note and also a screenshot of a ‘successful’ one. How does that look?