1# Troubleshooting
2
3## Diagnostics
4
5Run the doctor command to check your system:
6
7```bash
8dumber doctor           # Full check
9dumber doctor --runtime # GTK4/WebKitGTK only
10dumber doctor --media   # GStreamer/VA-API only
11```
12
13## Common Issues
14
15### Browser won't start
16
17**Symptoms:** Error about missing libraries or GTK/WebKitGTK version
18
19**Solution:**
201. Run `dumber doctor --runtime`
212. Install missing dependencies:
22   - Arch: `pacman -S webkitgtk-6.0 gtk4`
23   - Fedora: `dnf install webkitgtk6.0 gtk4`
24   - Ubuntu: `apt install libwebkitgtk-6.0-4 libgtk-4-1`
25
26### Video playback issues
27
28**Symptoms:** Videos don't play, high CPU usage, or Error #4000 on Twitch
29
30**Solution:**
311. Run `dumber doctor --media`
322. Check hardware decoding:
33   ```toml
34   # ~/.config/dumber/config.toml
35   [media]
36   hardware_decoding = "auto"  # Try "disable" if issues persist
37   ```
383. Install VA-API drivers:
39   - AMD: `libva-mesa-driver`
40   - Intel: `intel-media-driver`
41   - NVIDIA: `libva-nvidia-driver`
42
43### Screen flickering on Wayland
44
45**Symptoms:** Flicker when scrolling or rendering
46
47**Solution:**
48```toml
49[rendering]
50disable_dmabuf_renderer = true
51```
52
53### Fonts look wrong
54
55**Symptoms:** Missing characters, wrong font rendering
56
57**Solution:**
58```toml
59[appearance]
60sans_font = "Your Preferred Font"
61monospace_font = "Your Mono Font"
62default_font_size = 16
63```
64
65### High memory usage
66
67**Symptoms:** Browser uses too much RAM
68
69**Solution:**
70```toml
71[performance]
72profile = "lite"  # Reduces resource usage
73```
74
75### Session not restoring
76
77**Symptoms:** Previous tabs/panes don't restore on startup
78
79**Solution:**
801. Check session auto-restore:
81   ```toml
82   [session]
83   auto_restore = true
84   ```
852. List sessions: `dumber sessions list`
863. Manually restore: `dumber sessions restore <id>`
87
88### Launcher integration not working
89
90**Symptoms:** Rofi/fuzzel doesn't show history or icons
91
92**Solution:**
931. Ensure PNG favicons are cached:
94   ```bash
95   dumber dmenu | head -5  # Should show entries with icon paths
96   ```
972. Check rofi/fuzzel supports icons:
98   ```bash
99   dumber dmenu | rofi -dmenu -show-icons
100   ```
101
102## Logs
103
104View application logs for debugging:
105
106```bash
107dumber logs              # List sessions
108dumber logs <session-id> # View specific session
109dumber logs -f <id>      # Follow in real-time
110```
111
112## Reset Configuration
113
114If config is corrupted:
115
116```bash
117mv ~/.config/dumber/config.toml ~/.config/dumber/config.toml.bak
118dumber browse  # Creates new default config
119```
120
121## Complete Reset
122
123Remove all data and start fresh:
124
125```bash
126dumber purge
127```
128
129## Getting Help
130
131- Check logs: `dumber logs`
132- [GitHub Issues](https://github.com/bnema/dumber/issues)