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. Enable diagnostic mode for startup media warnings:
33
34   ```toml
35   # ~/.config/dumber/config.toml
36   [media]
37   show_diagnostics = true
38   gstreamer_debug_level = 3
39   ```
40
413. Check hardware decoding:
42
43   ```toml
44   # ~/.config/dumber/config.toml
45   [media]
46   hardware_decoding = "auto"  # Try "disable" if issues persist
47   ```
48
494. Install VA-API drivers:
50   - AMD: `libva-mesa-driver`
51   - Intel: `intel-media-driver`
52   - NVIDIA: `libva-nvidia-driver`
535. After diagnosing, disable diagnostic mode for quieter daily runs:
54
55   ```toml
56   [media]
57   show_diagnostics = false
58   gstreamer_debug_level = 0
59   ```
60
61### Screen flickering on Wayland
62
63**Symptoms:** Flicker when scrolling or rendering
64
65**Solution:**
66```toml
67[rendering]
68disable_dmabuf_renderer = true
69```
70
71### Fonts look wrong
72
73**Symptoms:** Missing characters, wrong font rendering
74
75**Solution:**
76```toml
77[appearance]
78sans_font = "Your Preferred Font"
79monospace_font = "Your Mono Font"
80default_font_size = 16
81```
82
83### High memory usage
84
85**Symptoms:** Browser uses too much RAM
86
87**Solution:**
88```toml
89[performance]
90profile = "lite"  # Reduces resource usage
91```
92
93### Session not restoring
94
95**Symptoms:** Previous tabs/panes don't restore on startup
96
97**Solution:**
981. Check session auto-restore:
99   ```toml
100   [session]
101   auto_restore = true
102   ```
1032. List sessions: `dumber sessions list`
1043. Manually restore: `dumber sessions restore <id>`
105
106### Launcher integration not working
107
108**Symptoms:** Rofi/fuzzel doesn't show history or icons
109
110**Solution:**
1111. Ensure PNG favicons are cached:
112   ```bash
113   dumber dmenu | head -5  # Should show entries with icon paths
114   ```
1152. Check rofi/fuzzel supports icons:
116   ```bash
117   dumber dmenu | rofi -dmenu -show-icons
118   ```
119
120## Logs
121
122View application logs for debugging:
123
124```bash
125dumber logs              # List sessions
126dumber logs <session-id> # View specific session
127dumber logs -f <id>      # Follow in real-time
128dumber crashes           # List unexpected-close reports
129dumber crashes show latest
130dumber crashes issue latest
131```
132
133## Reset Configuration
134
135If config is corrupted:
136
137```bash
138mv ~/.config/dumber/config.toml ~/.config/dumber/config.toml.bak
139dumber browse  # Creates new default config
140```
141
142## Complete Reset
143
144Remove all data and start fresh:
145
146```bash
147dumber purge
148```
149
150## Getting Help
151
152- Check logs: `dumber logs`
153- Check crash reports: `dumber crashes`
154- [GitHub Issues](https://github.com/bnema/dumber/issues)