1# Troubleshooting
2
3## Diagnostics
4
5Run the doctor command to check your system:
6
7```bash
8dumber doctor           # Full check
9dumber doctor --runtime # GTK and WebKit fallback runtime checks only
10dumber doctor --media   # GStreamer/VA-API only
11```
12
13## Common Issues
14
15### Browser won't start
16
17**Symptoms:** Error about the default CEF runtime, GTK libraries, or WebKitGTK fallback version.
18
19**Solution:**
201. If the error mentions GTK or the WebKit fallback, run `dumber doctor --runtime`.
212. Match the fix to the backend in the error:
22   - **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.
23   - **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`.
24
25### Video playback issues
26
27**Symptoms:** Videos don't play, high CPU usage, or Error #4000 on Twitch
28
29**Solution:**
301. Run `dumber doctor --media`
312. If the issue occurs with `engine.type = "webkit"`, enable GStreamer startup diagnostics:
32
33   ```toml
34   # ~/.config/dumber/config.toml
35   [media]
36   show_diagnostics = true
37
38   [engine.webkit]
39   gstreamer_debug_level = 3
40   ```
41
42   For the default CEF backend, skip `engine.webkit.gstreamer_debug_level`; it only affects the WebKit fallback.
43
443. Check hardware decoding:
45
46   ```toml
47   # ~/.config/dumber/config.toml
48   [media]
49   hardware_decoding = "auto"  # Try "disable" if issues persist
50   ```
51
524. Install VA-API drivers:
53   - AMD: `libva-mesa-driver`
54   - Intel: `intel-media-driver`
55   - NVIDIA: `libva-nvidia-driver`
565. After diagnosing the WebKit fallback, disable diagnostic mode for quieter daily runs:
57
58   ```toml
59   [media]
60   show_diagnostics = false
61
62   [engine.webkit]
63   gstreamer_debug_level = 0
64   ```
65
66### Screen flickering on Wayland with the WebKit fallback
67
68**Symptoms:** Flicker when scrolling or rendering while using `engine.type = "webkit"`
69
70**Solution:**
71
72```toml
73[engine.webkit]
74disable_dmabuf_renderer = true
75```
76
77### Fonts look wrong
78
79**Symptoms:** Missing characters, wrong font rendering
80
81**Solution:**
82
83```toml
84[appearance]
85sans_font = "Your Preferred Font"
86monospace_font = "Your Mono Font"
87default_font_size = 16
88```
89
90### High memory usage
91
92**Symptoms:** Browser uses too much RAM
93
94**Solution:**
95
96```toml
97[engine]
98profile = "lite"  # Reduces resource usage
99```
100
101### Session not restoring
102
103**Symptoms:** Previous tabs/panes don't restore on startup
104
105**Solution:**
1061. Check session auto-restore:
107   ```toml
108   [session]
109   auto_restore = true
110   ```
1112. List sessions: `dumber sessions list`
1123. Manually restore: `dumber sessions restore <id>`
113
114### Launcher integration not working
115
116**Symptoms:** Rofi/fuzzel doesn't show history or icons
117
118**Solution:**
1191. Ensure PNG favicons are cached:
120   ```bash
121   dumber dmenu | head -5  # Should show entries with icon paths
122   ```
1232. Check rofi/fuzzel supports icons:
124   ```bash
125   dumber dmenu | rofi -dmenu -show-icons
126   ```
127
128## Logs
129
130View application logs for debugging:
131
132```bash
133dumber logs              # List sessions
134dumber logs <session-id> # View specific session
135dumber logs -f <id>      # Follow in real-time
136dumber crashes           # List unexpected-close reports
137dumber crashes show latest
138dumber crashes issue latest
139```
140
141## Reset Configuration
142
143If config is corrupted:
144
145```bash
146mv ~/.config/dumber/config.toml ~/.config/dumber/config.toml.bak
147dumber browse  # Creates new default config
148```
149
150## Complete Reset
151
152Remove all data and start fresh:
153
154```bash
155dumber purge
156```
157
158## Getting Help
159
160- Check logs: `dumber logs`
161- Check crash reports: `dumber crashes`
162- [GitHub Issues](https://github.com/bnema/dumber/issues)