Skip to content

5.2 Troubleshooting

Jump to bottom
Thorin-Oakenpants edited this page May 15, 2022 · 8 revisions

🟩 FOREWORD

Before opening a new troubleshooting issue, do some CHECKS and CONFIRM the problem is caused by an arkenfox pref(s).

🟪 CHECK

  • 🔹 Check the wiki list of common overrides
    • 🔹 Including items tagged with [SETUP- in the user.js
    • 🔹 Including RFP side effects
  • 🔹 Check our override recipes
  • 🔹 Check already answered issues
  • 🔹 Check your "parrot" and console for syntax errors 1
  • 🔹 Check the console
    • Open the Browser Console (Ctrl+Shift+J) and/or Web Console (Ctrl+Shift+K) and clear it
    • Then repeat the action / task that is not working as intended, and see if the console logs anything
  • 🔹 Linux users
    • Check the source RPM/PKGBUILD/etc of your distro to see if they set any default vendor preferences

1 PARROTS

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, but use any pref name you like for your overrides

/* my overrides */
user_pref("_overrides.parrot", "overrides: started");
user_pref("pref.name.example", "green"); // I like green
user_pref("_overrides.parrot", "overrides: success");

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

🟪 CONFIRM

Confirm your issue is caused by arkenfox supported prefs in a new profile.

  • 🔹 IS IT UPSTREAM?
    • No pref changes and no extensions (unless the problem being tested is the extension)
    • If the problem still occurs, this is an upstream bug
  • 🔹 IS IT ARKENFOX?
    • Add arkenfox (with relevant overrides 1 if applicable) and restart
    • If the problem doesn't occur, then the issue is not arkenfox

1 Relevant overrides are those listed in arkenfox for users to implement: i.e not items listed as DON'T TOUCH or DON'T BOTHER

🟪 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).

To run the script:

  • 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

If an arkenfox pref(s) is confirmed as the cause, and you haven't found an existing answer, or you haven't found a console clue and tested some individual looking likely prefs, then you can do some manual testing to quickly narrow it down.

TEST PROFILE

  • 🔹 Create a new TEST profile with an empty user.js. Bookmark your test page(s), and add an extension if it is an extension issue that you are testing
  • 🔹 Copy the TEST profile for quick restoring if needed

MANUAL

  • 🔹 In the TEST profile, add the first or next section to the user.js and save, restart, test
  • 🔹 Repeat until the issue appears, now you know the section with the problematic pref

BINARY

  • 🔸 Binary: you eliminate half the remaining suspects each time
  • 🔹 In the TEST profile, add half of "your" user.js to the user.js and save, restart Firefox and test
    • 🔹 If the problem exists, you know it was in the first half
      • 🔸 Reset the profile, add half of the prefs tested
    • 🔹 If the problem does not exist, you know it is in the second half
      • 🔸 Don't reset the profile, just add half of the remaining prefs
  • 🔹 Repeat to narrow it down

PREF BY PREF

  • 🔹 Once you have narrowed down the possible prefs, you can test by toggling each one in about:config
    • It is good practice to use a new tab each test
Clone this wiki locally