Troubleshooting

Diagnostics

Run the doctor command to check your system:

dumber doctor           # Full check
dumber doctor --runtime # GTK and WebKit fallback runtime checks only
dumber doctor --media   # GStreamer/VA-API only

Common Issues

Browser won't start

Symptoms: Error about the default CEF runtime, GTK libraries, or WebKitGTK fallback version.

Solution:

1. If the error mentions GTK or the WebKit fallback, run dumber doctor --runtime.
2. Match the fix to the backend in the error:
   • Default CEF backend: install or provide a CEF runtime. On Arch, use pacman -S cef. On Fedora or Ubuntu, install an available CEF runtime/package or set engine.cef.cef_dir to a downloaded runtime.
   • GTK/WebKit fallback backend: install GTK4 and WebKitGTK. On Arch, use pacman -S webkitgtk-6.0 gtk4. On Fedora, install GTK4 and WebKitGTK packages from your distribution. On Ubuntu, use apt install libwebkitgtk-6.0-4 libgtk-4-1.

Video playback issues

Symptoms: Videos don't play, high CPU usage, or Error #4000 on Twitch

Solution:

1. Run dumber doctor --media

2. If the issue occurs with engine.type = "webkit", enable GStreamer startup diagnostics:

   # ~/.config/dumber/config.toml
   [media]
   show_diagnostics = true
   
   [engine.webkit]
   gstreamer_debug_level = 3
   

   For the default CEF backend, skip engine.webkit.gstreamer_debug_level; it only affects the WebKit fallback.

3. Check hardware decoding:

   # ~/.config/dumber/config.toml
   [media]
   hardware_decoding = "auto"  # Try "disable" if issues persist
   

4. Install VA-API drivers:

   • AMD: libva-mesa-driver
   • Intel: intel-media-driver
   • NVIDIA: libva-nvidia-driver

5. After diagnosing the WebKit fallback, disable diagnostic mode for quieter daily runs:

   [media]
   show_diagnostics = false
   
   [engine.webkit]
   gstreamer_debug_level = 0
   

Screen flickering on Wayland with the WebKit fallback

Symptoms: Flicker when scrolling or rendering while using engine.type = "webkit"

Solution:

[engine.webkit]
disable_dmabuf_renderer = true

Fonts look wrong

Symptoms: Missing characters, wrong font rendering

Solution:

[appearance]
sans_font = "Your Preferred Font"
monospace_font = "Your Mono Font"
default_font_size = 16

High memory usage

Symptoms: Browser uses too much RAM

Solution:

[engine]
profile = "lite"  # Reduces resource usage

Session not restoring

Symptoms: Previous tabs/panes don't restore on startup

Solution:

1. Check session auto-restore:

   [session]
   auto_restore = true
   

2. List sessions: dumber sessions list
3. Manually restore: dumber sessions restore <id>

Launcher integration not working

Symptoms: Rofi/fuzzel doesn't show history or icons

Solution:

1. Ensure PNG favicons are cached:

   dumber dmenu | head -5  # Should show entries with icon paths
   

2. Check rofi/fuzzel supports icons:

   dumber dmenu | rofi -dmenu -show-icons
   

Logs

View application logs for debugging:

dumber logs              # List sessions
dumber logs <session-id> # View specific session
dumber logs -f <id>      # Follow in real-time
dumber crashes           # List unexpected-close reports
dumber crashes show latest
dumber crashes issue latest

Reset Configuration

If config is corrupted:

mv ~/.config/dumber/config.toml ~/.config/dumber/config.toml.bak
dumber browse  # Creates new default config

Complete Reset

Remove all data and start fresh:

dumber purge

Getting Help

• Check logs: dumber logs
• Check crash reports: dumber crashes
• GitHub Issues