Add troubleshooting guide

2025-07-30 23:20:51 +02:00
parent 3978d184ac
commit 50144e083e
2 changed files with 162 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -30,6 +30,9 @@ Setting up a personal homelab using a ThinkPad laptop running Arch Linux to move
 - Next: Network domain setup and self-hosted services

 ## Documentation & TODO Lists
+
+**[troubleshooting.md](troubleshooting.md)** - General troubleshooting for any issues found
+
 - [x] **[arch-install-notes.md](arch-install-notes.md)** - Installation process and core system setup
 - [ ] **[arch-linux-setup.md](arch-linux-setup.md)** - General Arch Linux configuration tasks
 - [ ] **[yadm-setup-notes.md](yadm-setup-notes.md)** - Dotfiles management and development environment setup
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -0,0 +1,159 @@
+# Bluetooth keeps disconnecting - reconnecting
+
+Solution: Change config in /etc/bluetooth/main.conf
+`ControllerMode = bredr`
+Then `sudo systemctl restart bluetooth`
+
+UPDATE: It's still not fixed :(
+Trying `yay -S pipewire wireplumber`
+
+# Touchpad scroll direction (libinput)
+
+To change touchpad scroll direction on Arch Linux using libinput driver:
+
+## Investigation steps:
+1. Check which driver is used: `pacman -Q | grep -E "(synaptics|libinput)"`
+2. Verify libinput config exists: `ls /usr/share/X11/xorg.conf.d/ | grep libinput`
+
+## Solution for libinput:
+Create `/etc/X11/xorg.conf.d/30-touchpad.conf`:
+
+```
+Section "InputClass"
+    Identifier "touchpad"
+    Driver "libinput"
+    MatchIsTouchpad "on"
+    Option "NaturalScrolling" "true"
+    Option "Tapping" "on"
+    Option "TappingDrag" "on"
+    Option "DisableWhileTyping" "on"
+EndSection
+```
+
+Set `NaturalScrolling` to:
+- `"true"` for macOS-style (natural) scrolling
+- `"false"` for traditional scrolling
+
+Restart X11 (log out/in) or reboot to apply changes.
+
+## Alternative: Synaptics driver (legacy)
+
+If using the older synaptics driver instead of libinput:
+
+### Investigation steps:
+1. Check for synaptics: `pacman -Q xf86-input-synaptics`
+2. Look for config: `ls /usr/share/X11/xorg.conf.d/ | grep synaptics`
+
+### Solution:
+Create `/etc/X11/xorg.conf.d/70-synaptics.conf`:
+
+```
+Section "InputClass"
+    Identifier "touchpad"
+    Driver "synaptics"
+    MatchIsTouchpad "on"
+    MatchDevicePath "/dev/input/event*"
+    Option "VertScrollDelta" "-111"
+    Option "HorizScrollDelta" "-111"
+    Option "TapButton1" "1"
+    Option "TapButton2" "3"
+    Option "TapButton3" "2"
+    Option "PalmDetect" "1"
+    Option "SHMConfig" "on"
+EndSection
+```
+
+Synaptics scroll direction options:
+- `VertScrollDelta` and `HorizScrollDelta`:
+  - Positive values (e.g., `"111"`) for traditional scrolling
+  - Negative values (e.g., `"-111"`) for natural/reversed scrolling
+
+**Note:** libinput is the modern standard. Consider switching from synaptics to libinput for better support and features.
+
+# Theme switching issues
+
+## Tmux and terminal not updating after theme switch
+
+**Issue:** After running the theme switcher script, tmux sessions and existing terminals don't reflect the new theme until restarted.
+
+**Temporary workaround:** 
+- Restart tmux sessions: `tmux kill-server && tmux`
+- Open new terminal windows
+
+**TODO:** 
+- Investigate tmux theme reload without killing sessions
+- Check if terminal emulator supports theme change signals
+- Improve theme script to handle live theme updates
+
+## Tmux window names showing hostname instead of command
+
+**Issue:** Tmux windows show "homelab" (hostname) for inactive tabs but correct command names for active tabs.
+
+**Root cause:** Catppuccin tmux theme with `@catppuccin_window_tabs_enabled on` uses different text formatting for active vs inactive windows.
+
+**Solution:** Disable catppuccin window tabs:
+```
+set -g @catppuccin_window_tabs_enabled off
+```
+
+**Alternative:** Configure explicit window text for both states:
+```
+set -g @catppuccin_window_default_text "#W"
+set -g @catppuccin_window_current_text "#W"  
+```
+
+Also ensure automatic renaming is enabled:
+```
+setw -g automatic-rename on
+setw -g allow-rename on
+```
+
+# Font and Unicode Display Issues
+
+## Missing emoji and unicode symbols
+
+**Issue:** Emojis show as boxes or missing characters, unicode symbols don't display properly.
+
+**Solution:** Install comprehensive unicode font packages:
+```bash
+sudo pacman -S noto-fonts-emoji noto-fonts-extra
+fc-cache -f
+```
+
+## Nerd Font icons not displaying
+
+**Issue:** Developer icons (programming languages, git symbols, file types) show as blank spaces or boxes.
+
+**Root cause:** Terminal emulator not configured to use Nerd Font as primary font.
+
+**Solution:** 
+1. Install Nerd Fonts:
+```bash
+sudo pacman -S ttf-iosevkaterm-nerd ttf-jetbrains-mono-nerd
+fc-cache -f
+```
+
+2. Configure terminal to use Nerd Font as primary font
+3. For wezterm, ensure config includes:
+```lua
+config.font = wezterm.font_with_fallback {
+    'IosevkaTerm Nerd Font', 
+    'JetBrainsMono Nerd Font Mono', 
+    'Noto Color Emoji'
+}
+```
+
+**Testing:** Use printf with direct codepoints:
+```bash
+printf "Icons: \\ue702 \\uf121 \\uf015 \\uf07b\\n"
+```
+
+## Ancient/exotic script support
+
+**Comprehensive coverage achieved with:**
+- `noto-fonts` (base unicode)
+- `noto-fonts-cjk` (Chinese/Japanese/Korean)  
+- `noto-fonts-emoji` (color emoji)
+- `noto-fonts-extra` (additional scripts)
+
+Successfully displays: Egyptian hieroglyphs, Cuneiform, Nordic runes, Hungarian rovás, Arabic, Chinese, Japanese, Korean, Thai, Hindi, Hebrew, Greek, Tamil.