homelab/troubleshooting.md

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 TODO test it again

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

Cross-application theme synchronization

Issue: Need to synchronize theme (light/dark) across tmux, nvim, and other terminal applications.

Solution: File-based theme management system using ~/.vim_theme:

Setup:

1. Create theme switcher script (~/.config/tmux/themeswitch.sh):

#!/bin/bash
if [ -f ~/.vim_theme ] && [ "$(cat ~/.vim_theme)" = "light" ]; then
    tmux set -g @catppuccin_flavor "latte"
else
    tmux set -g @catppuccin_flavor "mocha"
fi

2. Add to tmux config (~/.config/tmux/tmux.conf):

# Dynamic theme switching based on ~/.vim_theme file
run 'bash ~/.config/tmux/themeswitch.sh'

3. Add to shell config (~/.zshrc):

# Export THEME environment variable for nvim and other apps
if [ -f ~/.vim_theme ]; then
    export THEME=$(cat ~/.vim_theme)
else
    export THEME="dark"  # default
fi

Usage:

# Switch to light theme
echo "light" > ~/.vim_theme

# Switch to dark theme
echo "dark" > ~/.vim_theme

Benefits:

• ✅ Single source of truth: ~/.vim_theme file controls all applications
• ✅ Automatic propagation: New terminals inherit theme via shell config
• ✅ No environment variable issues: File-based approach avoids tmux env var propagation problems
• ✅ Cross-application support: nvim reads $THEME, tmux uses catppuccin flavors

Limitations:

• Tmux live reload: Changes require tmux config reload or session restart
• Workaround: Use tmux-resurrect to quickly restore sessions after restart

Legacy: 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

Status: ✅ Solved - Use file-based theme management system above

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:

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:

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:

config.font = wezterm.font_with_fallback {
    'IosevkaTerm Nerd Font',
    'JetBrainsMono Nerd Font Mono',
    'Noto Color Emoji'
}

Testing: Use printf with direct codepoints:

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.

Cannot tile windows by drag and dropping

Keyboard workaround: Go to Settings > Window Manager > Keyboard, set up tiling shortcuts (set to Super+arrow keys)

Additional Known Issues (TODO Items)

Tmux battery indicator missing until config reload

Issue: Battery indicator doesn't appear in tmux status line immediately after starting tmux.

Temporary workaround: Reload tmux config with Prefix + r or restart tmux session.

Status: Investigation needed

TTY fallbacks needed

Issue: When not in X11/graphical mode, nvim and tmux need proper fallback configurations.

Status: Completed

Solutions implemented:

• ✅ nvim: TTY detection and color scheme fallback configured
• ✅ Font: Selected ter-124b (12x24 bold) for good readability
• ✅ Keyboard: Colemak layout with caps lock remapped to backspace
• ✅ Caps lock fix: Uses systemd service with setkeycodes 3a 14

Configuration files:

• /etc/systemd/system/caps-backspace.service - Permanent caps lock remapping
• TTY font testing script: ~/.local/scripts/test-fonts.sh

TTY Caps Lock Not Working as Backspace

Issue: With colemak keymap loaded, caps lock acts like Control instead of backspace in TTY.

Root cause: Colemak keymap maps caps lock to Control, which conflicts with tmux navigation keys.

Solution: Use setkeycodes to remap at scancode level:

sudo setkeycodes 3a 14  # Map caps lock scancode to backspace keycode

Permanent fix: Systemd service created at /etc/systemd/system/caps-backspace.service

Laptop sleeps when lid is closed

Solution:

sudo nvim /etc/systemd/logind.conf

Uncomment and change these lines:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

Then restart service: sudo systemctl restart systemd-logind