Skip to content

5.2 Troubleshooting

Jump to bottom
Thorin-Oakenpants edited this page Jan 29, 2022 · 8 revisions

Besides asking and guessing, the only way to find the cause(s) of why something doesn't work as expected, is to methodically eliminate preferences. And only after it is confirmed that the user.js is the cause, by replicating the problem in a new profile with no extensions.

🔸 Did an extension break?

We have an "unofficial" sticky issue here for prefs that can break extensions

🔸 Check your "parrot" and console

When you modify your user.js, such as adding any overrides, sometimes syntax errors happen. Open about:config and check your "parrot". Arkenfox uses _user.js.parrot throughout the user.js. You can use any pref name you like, as long as it's different (to avoid confusion).

example

/* my overrides */
user_pref("canary.in.a.coalmine", "overrides: started"); // parrot, canary, whatever you like

user_pref("toolkit.legacyUserProfileCustomizations.stylesheets", true); // userChrome/userContent
user_pref("ui.key.menuAccessKey", 0); // disable alt key toggling the menu bar [RESTART]
user_pref("browser.tabs.extraDragSpace", false); // stop theme turning drag space on

user_pref("canary.in.a.coalmine", "overrides: success");

Note: not all syntax errors cause the user.js parsing to be aborted. After Firefox opens, open the Browser Console (Ctrl+Shift+J) and check for any pref-parsing related warnings/errors, fe:

🔸 Use the Browser Console

Open the Browser Console (Ctrl+Shift+J) and clear it. Then repeat the action / task that is not working as intended, and see if the console logs anything. If it does but you can't decipher what it means, feel free to post the error message in a new issue and maybe we can help. But do try and dig a little deeper first

🔸 Tags

While not 100% definitive, we have included [SETUP* tags for troubleshooting (and setting up). Some examples

  • [SETUP-WEB] can cause some websites to break
  • [SETUP-CHROME] changes how Firefox itself behaves (i.e. NOT directly website related)
  • [SETUP-PERF] may impact performance

🔸 Use our scratchpad script

Before you go on to the laborious task of manual troubleshooting you should try our troubleshooter script first. In many cases it will be able to either directly identify the culprit or at least narrow it down to a more manageable number of prefs for manual troubleshooting. You can just run the script and follow the instructions but we strongly recommend to watch the demo video first (webm, 62mb, 16m26s).

Mozilla removed the Scratchpad in FF72 but you can still run the script via the Web Console:

  • Load about:config and press Ctrl+Shift+K to open the Web Console for about:config
  • Switch to multi-line editor mode (Ctrl+B toggles between single- and multi-line editor mode)
  • Load (or paste) the troubleshooter script, run it and follow the instructions

🔸 Manual troubleshooting

  1. Download and unpack a portable Firefox
    • Current stable Firefox portable is always here
    • Older versions are here
  2. Create a profile and test the problem
    • Open Firefox and go to the web page where you can replicate the problem and bookmark it
    • Verify that the problem does not exist in a vanilla Firefox setup.
  3. Set up a profile-master for quick resets
    • Close Firefox
    • Go to the \FirefoxPortable\Data\profile folder and create an empty user.js file
    • Then go up a directory to the \FirefoxPortable\Data\ folder and COPY the profile folder. Rename it profile-master (we can use this to quickly restore to a vanilla profile)
  4. Make sure the user.js is the cause
    • Replace the user.js in your profile folder with the full user.js.
    • Restart Firefox and confirm the problem exists
  5. Reset the profile folder
    • Close Firefox
    • Go to the \FirefoxPortable\Data\ folder and delete the profile folder.
    • COPY the profile-master folder and rename it profile
  6. Addition method (do step 6 or 7)
    • In your profile user.js (which initially should be empty), paste in the section (or sections) you suspect might be the culprit, save the changes and restart Firefox.
    • Test if the problem exists. If not repeat the above step until you find it.
  7. Halving method (do step 6 or 7)
    • This method involves re-setting your vanilla profile often (see step 5)
    • Use this method if you have no idea what section could be the cause. By testing half and then based on the results, testing the next quarter, and then based on those results testing the next eighth etc, you can rapidly narrow it down in four or five steps at most.
    • In a reset profile (see step 5), edit the user.js and paste in half the sections eg 0100-1400, and save the changes. Restart Firefox and test if the problem exists. If it does we now know it is the 0100-1400 half that contains the culprit. If not, we know it is the 1600-end half. For this example the problem didn't occur.
    • In a reset profile, edit the user.js and paste in half the 1600-end sections, eg 1600-2500, and save the changes. Restart Firefox and test if the problem exists. If it does we now know it is the 1600-2500 half that contains the culprit. If not, we know it is the 2600-end section.
    • Keep repeating these steps to narrow it down
    • You can also use this method to halve big sections such as 2600
  8. Checking preference by preference
    • In a reset profile (see step 5), paste in the offending section (or sections) into the user.js and save the changes. Restart Firefox.
    • Go to about:config, find the first preference and right click and reset it. Test if the problem exists.
    • If the problem still exists, clear your cache and repeat the above step
Clone this wiki locally