Debugging

Strategies and tools for debugging Firefox / Gecko at every layer.

Logging

Gecko has multiple logging systems, layered roughly:

• MOZ_LOG environment variable plus mozilla::LogModule. Most C++ subsystems define LogModules and use MOZ_LOG(gMyLog, LogLevel::Debug, ("message")).

  MOZ_LOG="nsHttp:5" ./mach run
  MOZ_LOG_FILE=/tmp/firefox.log MOZ_LOG="cookie:5,nsHttp:5" ./mach run

  Levels: 0 (Disabled), 1 (Error), 2 (Warning), 3 (Info), 4 (Debug), 5 (Verbose). See mfbt/Logging.h.

• PR_LOG (legacy NSPR) — superseded by MOZ_LOG but still found in some networking and NSS code.

• Cu.reportError(...) / console.error(...) in JS → goes to the Browser Console.

• Glean events / metrics — for production telemetry, see features/telemetry-glean.md.

Built-in dev surfaces

• about:config — Preferences store. Most knobs (network.http.*, dom.*, privacy.*) live here.
• about:processes — Process list with per-process memory and CPU.
• about:memory — Detailed memory reports; includes a Save reports as JSON button.
• about:networking — Live socket / DNS / WebSocket / HTTP3 info.
• about:webrtc — WebRTC session state.
• about:support — Troubleshooting info; copy this when filing a bug.
• about:profiling (and Tools → Performance) — built-in profiler. The profile uploads to profiler.firefox.com.
• about:crashes — submitted crash reports.
• Browser Console (Cmd-Shift-J / Ctrl-Shift-J) — chrome-privileged console.
• Browser Toolbox (Cmd-Opt-Shift-I) — DevTools attached to the browser chrome itself.

Native debuggers

• ./mach run --debugger=lldb (or gdb, rr on Linux). For Windows, --debugger=visualstudio or windbg.

• ./mach run --debugger=rr — record-and-replay. Excellent for reproducing intermittents.

• For tests:

  ./mach mochitest --debugger=lldb path/to/test

• Debugging the content process: --setpref dom.ipc.processCount=1 --debugger-args="..." plus environment variables; the easier path is MOZ_DEBUG_CHILD_PROCESS=1.

JS debugging

• Tools → Web Developer → Debugger — debug page JS.
• Browser Toolbox — debug chrome JS (browser UI).
• For chrome JS, set devtools.chrome.enabled and devtools.debugger.remote-enabled to true.
• The integrated stack walker can dump JS stacks: Cu.dumpStack() from any chrome JS.

Sanitizers

• ASan, TSan, UBSan builds available; pre-built Nightlies live on Treeherder.
• Locally: ac_add_options --enable-address-sanitizer and friends in .mozconfig.

Crash analysis

• Crashes go to crash-stats.mozilla.com (via Socorro). Each report has a stack and metadata.
• The crash reporter client lives in toolkit/crashreporter/, with Rust components: client/app, crash_helper_server, crash_helper_client, mozwer-rust, minidump-analyzer/.

Tree introspection

• Searchfox — fast cross-reference search of mozilla-central. Indispensable.
• DXR (deprecated) — superseded by Searchfox.
• Treeherder — CI dashboards.
• Bugzilla — bug + history search.

Common runbooks

Symptom	First step
Build fails	./mach build-backend && ./mach build after editing moz.build. Try ./mach clobber.
Lint complains in CI but not locally	./mach lint --outgoing runs the same set; ensure you are on tip.
Mochitest hangs	Inspect MOZ_LOG="DocLoader:5" and run with --keep-open=true to inspect.
Crash on startup after a pull	Check CLOBBER changed; clobber and rebuild.
WPT differences	Update __dir__.ini, __test__.ini metadata; consult WPT docs.
Telemetry pings missing	Use about:telemetry and the Glean Debug View tooling.