Problem statement

I ran into a very confusing Firefox issue on Linux (Wayland):

  • firefox → freezes / not responding
  • firefox --kiosk → ✅ works
  • firefox --preferences → ✅ works
  • Creating a new tab or popup → ❌ freezes again
  • Disabling all extensions → ❌ still freezes
  • Creating a new Firefox profile → ✅ works
  • Deleting prefs.js → ✅ fixes it

At first glance this looks like:

  • an extension bug
  • GPU / cache corruption
  • session restore issue

But none of those were the real cause.

Key observation (the real clue)

Firefox worked only when it did not open a normal browser window:

ModeResult
Normal window (browser.xhtml)❌ freezes
Preferences window✅ works
Kiosk mode✅ works

This strongly suggests:

The Firefox browser chrome initialization path is broken on Wayland

Root cause (confirmed)

The problem was caused by this single preference in prefs.js:

user_pref("widget.wayland.opaque-region.enabled", false);

Removing this line instantly fixed everything.

Why this breaks Firefox on Wayland

On Wayland, Firefox relies on opaque regions to:

  • finalize window surfaces
  • coordinate with the compositor
  • complete browser chrome layout (browser.xhtml)
  • finish tab / toolbar / sidebar initialization

Setting this pref to false tells Firefox:

“This window is transparent; don’t assume any opaque area.”

That causes a compositor-level deadlock when Firefox tries to create a normal browser window.

Why it still works in other modes:

  • --preferences uses a different UI document
  • --kiosk bypasses much of the normal chrome/layout logic

How this pref usually sneaks in

This is an internal, undocumented preference.

It often comes from:

  • random Wayland “performance tweak” posts
  • Reddit / GitHub comments
  • copied Firefox optimization guides
  • experimentation with transparent titlebars or GTK behavior

⚠️ It should not be changed manually on modern Firefox.

The fix (safe and permanent)

1. Remove the bad pref

Edit your profile prefs.js and delete this line:

user_pref("widget.wayland.opaque-region.enabled", false);

Or from terminal:

pkill -9 firefox
sed -i '/widget\.wayland\.opaque-region\.enabled/d' ~/.mozilla/firefox/*.default*/prefs.js

Create or edit user.js in your profile:

nano ~/.mozilla/firefox/*.default*/user.js

Add:

user_pref("widget.wayland.opaque-region.enabled", true);

Firefox will now enforce the correct value on every startup.

Optional cleanup (after it works)

pkill -9 firefox
rm -f ~/.mozilla/firefox/*.default*/xulstore.json
rm -f ~/.mozilla/firefox/*.default*/browser-ui-state.json

This resets UI geometry safely.

How to quickly confirm this was your issue

Run Firefox using X11 instead of Wayland:

MOZ_ENABLE_WAYLAND=0 firefox

If this works immediately, it confirms the bug is Wayland widget-related.

Summary

  • ❌ Not an extension issue
  • ❌ Not a cache issue
  • ❌ Not a GPU driver issue
  • ✅ A single Wayland-specific pref caused Firefox to deadlock during UI creation

If Firefox works with --kiosk or --preferences but freezes normally on Wayland — check this pref first.

Final note

This kind of bug does not crash Firefox, so there is:

  • no crash report
  • no obvious error message
  • no helpful online answers

Hopefully this post saves someone else hours of debugging.