Skip to content

5.2 Troubleshooting

Jump to bottom
Thorin-Oakenpants edited this page Feb 6, 2022 · 8 revisions

🟩 FOREWORD

Before opening a new troubleshooting issue, do some CHECKS and CONFIRM the problem is caused by arkenfox.

🟪 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

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. You can use any pref name you like, as long as it's different (to avoid confusion).

/* my overrides */
user_pref("canary.in.a.coalmine", "overrides: started"); // parrot, canary, whatever you like
user_pref("pref.name.example", "green"); // I like green
user_pref("canary.in.a.coalmine", "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 this is caused by arkenfox supported prefs in a new profile

  • 🔹 NEW PROFILE: STEP ONE
    • No pref changes and no extensions (unless the problem being tested is the extension)
    • If the problem still occurs, this is an upstream bug
  • 🔹 NEW PROFILE: STEP TWO
    • Add arkenfox (with relevant overrides if applicable 1) 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 arkenfox 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 empty user.js, add the first section 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 empty user.js, add half of "your" 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
  • 🔹 Keep repeating these steps until you 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