lenovo-gentoo/Troubleshooting.md

Troubleshooting Guide

This guide contains troubleshooting commands and procedures for common issues on the Gentoo ThinkPad system.

Bluetooth Issues

Check Bluetooth Status

# Check controller
bluetoothctl list

# Check modules
lsmod | grep bt

# Check service
rc-service bluetooth status

# Check kernel messages
dmesg | grep -i bluetooth

Full Troubleshooting Guide

See Bluetooth-Setup.md for complete Bluetooth setup, troubleshooting, and technical details.

Power Management Issues

Check Power Profile Status

# Check logs
tail -50 /var/log/power-profile.log

# Check current state
cat /sys/class/power_supply/AC/online  # 1 = AC, 0 = battery
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# Manual profile test
sudo /usr/local/bin/power-profile-ac      # Performance mode
sudo /usr/local/bin/power-profile-battery # Power saving mode

Full Troubleshooting Guide

See Power-Management-Setup.md for complete details and advanced configuration.

WiFi Issues

Check WiFi Status

# Check status
wifi-setup status

# Check waybar integration
emerge -pv gui-apps/waybar | grep network

# Check network interface
ip link show wlp194s0

# Check NetworkManager
nmcli device status

Full Troubleshooting Guide

See scripts/wifi-setup/README.md for complete setup instructions, usage examples, and troubleshooting.

Audio Issues

Check Audio Status

# Check status
audio-setup status

# List devices
audio-setup list-outputs
audio-setup list-inputs

# Check PulseAudio
pactl info

# Check ALSA
aplay -l  # List playback devices
arecord -l  # List recording devices

Full Troubleshooting Guide

See scripts/audio-setup/README.md for complete setup instructions, usage examples, and troubleshooting.

Monitor/Lid Issues

Check Monitor Configuration

# Check logs
cat /tmp/lid-handler.log

# Check monitor configuration
monitor-setup status
hyprctl monitors

# Check ACPI events
acpi_listen  # Run this, then open/close lid to see events

# Check elogind
loginctl show-session $XDG_SESSION_ID

# Check Hyprland monitor script
/home/alexander/.config/hypr/scripts/monitor-setup.sh

Full Troubleshooting Guides

• Lid-Automation-Working-Solution.md - Lid automation implementation
• Fix-DisplayLink-Artifacts.md - DisplayLink optimization guide

Monitor Management Issues

Interactive Monitor Commands

# Check current layout
monitor-setup status

# List all monitors
monitor-setup list

# Swap if order is wrong
sudo monitor-setup swap

# Reset to auto-detection
sudo monitor-setup reset

Full Troubleshooting Guide

See scripts/monitor-setup/README.md for complete setup instructions, usage examples, and troubleshooting.

Battery Conservation Issues

Check Battery Thresholds

# Check current thresholds
battery-setup status

# Check if thresholds are supported
ls /sys/class/power_supply/BAT*/charge_control_*_threshold

# Check OpenRC service
rc-service battery-thresholds status

# Manually set thresholds
sudo battery-setup conservation

# Check battery health
cat /sys/class/power_supply/BAT0/capacity
cat /sys/class/power_supply/BAT0/cycle_count
cat /sys/class/power_supply/BAT0/status

# Check ThinkPad ACPI module
lsmod | grep thinkpad_acpi

Full Troubleshooting Guide

See scripts/battery-setup/README.md for complete setup instructions, battery science, and troubleshooting.

Backup Issues

Check Backup Status

# Check backup status
backup-setup status

# Check if NAS is reachable
ping -c 3 192.168.2.171
ssh alexander@192.168.2.171 "echo test"

# Check network trigger logs
tail -20 ~/.local/var/log/backup-monitor.log

# Check backup logs
tail -50 ~/.local/var/log/backup.log

# Check for active backups
ls -la /tmp/backup-*.lock

# Remove stale lock files (if older than 6 hours)
rm /tmp/backup-*.lock

# Check backup service
sudo rc-service backup-monitor status

Manual Backup Commands

# Run manual backup
backup-setup full     # Full system backup
backup-setup home     # Home directory only
backup-setup configs  # Configuration files only
backup-setup incremental  # Incremental backup

# Check last backup time
cat ~/.local/var/backup/last-backup

Full Troubleshooting Guide

See Backup-Setup.md for complete backup guide - Automated NAS backups, network trigger, troubleshooting.

Firewall Issues

Check Firewall Status

# Check firewall status
sudo rc-service nftables status

# View firewall rules
sudo nft list ruleset

# Test connectivity
ping -c 3 8.8.8.8  # Internet connectivity
ping -c 3 192.168.2.171  # NAS connectivity

# Check if port is blocked
sudo nft list ruleset | grep <port_number>

# Restart firewall
sudo rc-service nftables restart

# Test specific service
telnet <host> <port>

Full Troubleshooting Guide

See Security-Hardening.md for complete security guide - Firewall, fail2ban, SSH hardening, monitoring.

Ghostty Terminal Issues

Check Ghostty Status

# Test if Ghostty works
ghostty

# Check if it's pure Wayland (should show nothing)
ldd /usr/bin/ghostty | grep -i x11

# Check Hyprland keybinding
grep ghostty ~/.config/hypr/hyprland.conf

# Check Ghostty config
cat ~/.config/ghostty/config

# Run Ghostty with debug output
ghostty --verbose

Ghostty Configuration

Location: ~/.config/ghostty/config

Package Configuration: See CLAUDE.md section "Ghostty Terminal Emulator" for complete USE flags and build configuration.

Neovim/LSP Issues

Check LSP Status

# Check LSP servers are working
nvim  # Open Neovim
:LspInfo  # Check LSP status

# Check for LSP errors
:messages

# Verify new API is being used (no deprecation warnings)
# Start nvim and check for warnings about lspconfig

# Test a file with LSP support
nvim test.go  # Should show LSP features

# Check Neovim version
nvim --version  # Should be 0.11+

# Check LSP config location
ls -la ~/.config/nvim/lua/alxndrhi/plugins/lsp.lua

LSP Configuration

Location: ~/.config/nvim/lua/alxndrhi/plugins/lsp.lua

API: Uses Neovim 0.11+ native vim.lsp.config[] API (not deprecated require('lspconfig'))

Configured Servers: html, cssls, gopls, clangd, jsonls, yamlls, bashls, dockerls, vimls, lua_ls, ruff, graphql, tailwindcss, vuels, cmake

Theme/Waybar Issues

Check Waybar Theme

# Check waybar is using correct CSS file
# Look for: "Using CSS file /home/alexander/.config/waybar/style.css"
killall waybar && waybar 2>&1 | head -20

# Verify Nerd Font is available
fc-list | grep -i hasklug

# Test icon display in terminal
echo "CPU: 󰻠  RAM:   WiFi: 󰖩  Volume: 󰕿"

# Check if Catppuccin colors are applied
cat ~/.config/waybar/style.css | grep "#1e1e2e"  # Should show base color

# Restart waybar to apply changes
killall waybar && waybar &

# Check Hyprland colors
hyprctl clients | grep -A 5 "Window"  # Should show borders

# View Hyprland color configuration
cat ~/.config/hypr/mocha.conf

Waybar Configuration Files

• ~/.config/waybar/config - Module configuration with icon definitions
• ~/.config/waybar/style.css - Catppuccin Mocha theme with color-coded modules
• ~/.config/waybar/mocha.css - Catppuccin Mocha color palette definitions

Hyprland Theme Files

• ~/.config/hypr/hyprland.conf - Window border colors
• ~/.config/hypr/mocha.conf - Catppuccin Mocha color variables

Dotfile Management (chezmoi) Issues

Common Chezmoi Problems

# Warning about config template changed
chezmoi init

# Diff shows nothing or just "pppp"
chezmoi diff --use-builtin-diff | less

# File conflicts
chezmoi merge ~/.zshrc
# Or force overwrite:
chezmoi apply --force

# Template errors
chezmoi cat ~/.zshrc  # See rendered output
chezmoi execute-template "{{ .chezmoi.os }}"  # Test expression

# Re-run installation scripts
chezmoi state reset --bucket=scriptState
chezmoi apply

# Check configuration
chezmoi data  # View all variables
cat ~/.config/chezmoi/chezmoi.yaml

# Remove file from management
chezmoi forget ~/.file

# Complete reset (DESTRUCTIVE - removes all managed files)
chezmoi purge

Chezmoi Configuration

Source Directory: ~/.local/share/chezmoi (git clone of dotfiles repo)

Dotfiles Repository: ~/repository/git.hinrichs.dev/alexander/dotfiles

Config File: ~/.config/chezmoi/chezmoi.yaml (generated from .chezmoi.yaml.tmpl)

Full Troubleshooting Guide

See Dotfiles-Management.md for complete chezmoi guide - Managing dotfiles, adding new tools, editing configs.

Kernel Issues

Check Kernel Configuration

# Check current kernel version
uname -r

# Extract current running config
zcat /proc/config.gz > /tmp/current-config

# Check specific kernel option
zcat /proc/config.gz | grep CONFIG_PINCTRL_AMD

# Check loaded modules
lsmod

# Check kernel messages
dmesg | less

# Check for kernel errors
dmesg | grep -i error
dmesg | grep -i fail

Kernel Build Issues

⚠️ CRITICAL: NEVER use genkernel. Always use manual kernel compilation or the automated build script.

Build Script: scripts/build-kernel.sh

Saved Config: kernel-6.12.41-gentoo-x86_64.config

Build Logs: logs/kernel-build-TIMESTAMP.log

Manual Kernel Build

# Extract current running config
zcat /proc/config.gz > /usr/src/linux/.config

# Edit config as needed
cd /usr/src/linux
sudo make menuconfig

# Or use automated script
sudo ./scripts/build-kernel.sh

See CLAUDE.md section "Kernel Configuration" for complete build process.

Touchpad/Touchscreen Issues

Check I2C HID Devices

# Check if devices are detected
dmesg | grep -i elan

# Check if modules are loaded
lsmod | grep i2c_hid

# Check device nodes
ls -la /dev/input/by-path/ | grep i2c

# Check Hyprland input devices
hyprctl devices

# Test touchpad events
libinput debug-events

Hardware Details

• Touchpad: ELAN901C I2C HID device (ACPI: ELAN901C:00, PNP0C50)
• Touchscreen: ELAN0678 I2C HID multitouch display (ACPI: ELAN0678:00, PNP0C50)

Required Kernel Options

• CONFIG_I2C_HID=m
• CONFIG_I2C_HID_ACPI=m
• CONFIG_PINCTRL_AMD=y (CRITICAL for GPIO interrupts on AMD platforms)

Full Documentation

See Touchpad-Touchscreen-Setup.md and POST-REBOOT-CHECKLIST.md

Webcam Issues

Check Webcam Status

# Check if webcam is detected
lsusb | grep -i camera

# Check kernel messages
dmesg | grep -i uvc

# List video devices
ls -la /dev/video*

# Check video device capabilities (requires v4l-utils)
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --list-formats-ext

# Test capture (requires ffmpeg)
ffmpeg -f v4l2 -i /dev/video0 -frames:v 1 test.jpg

# Check user permissions
groups | grep video

Hardware Details

• Model: Luxvisions Innotech Limited Integrated RGB Camera
• USB ID: 30c9:00f4
• Resolution: 640x480 @ 30fps (default)
• Driver: uvcvideo (USB Video Class)
• Device Nodes: /dev/video0-3

Docker Issues

Check Docker Status

# Check Docker service
rc-service docker status

# Check Docker version
docker --version

# Test Docker
docker run hello-world

# Check Docker logs
docker logs <container_id>

# Check Docker network
docker network ls

Docker Firewall Integration

If Docker containers cannot reach the internet, check firewall rules:

# Check if Docker chain exists in nftables
sudo nft list ruleset | grep docker

# Uncomment Docker forwarding rules in /etc/nftables.conf
# Then restart:
sudo rc-service nftables restart

See Security-Hardening.md for Docker firewall integration.

General System Troubleshooting

Service Management (OpenRC)

# List all services
rc-status -a

# Start/stop/restart service
sudo rc-service <service> start
sudo rc-service <service> stop
sudo rc-service <service> restart

# Enable/disable service at boot
sudo rc-update add <service> default
sudo rc-update del <service> default

# Check service logs
tail -f /var/log/<service>.log

System Logs

# View system messages
dmesg | less

# View recent errors
dmesg | grep -i error | tail -20

# View kernel ring buffer
journalctl -k  # If using systemd-journald

# Check OpenRC logs
ls -la /var/log/rc.log

Package Management (Gentoo)

# Search for package
emerge --search <package>

# Check package info
emerge --info <package>

# List installed packages
qlist -I

# Check for config file updates
dispatch-conf

# Rebuild @world
emerge -avuDN @world

Performance Monitoring

# CPU usage
top
htop

# Memory usage
free -h

# Disk usage
df -h
du -sh /*

# I/O statistics
iostat -x 2

# Network statistics
iftop
nethogs

Getting Help

Documentation Files

• USER-GUIDE.md - Quick reference for everyday tasks
• System-Overview.md - Hardware specs and software stack
• Feature-Status.md - Current state and working features
• Backup-Setup.md - Complete backup guide
• Security-Hardening.md - Complete security guide
• Power-Management-Setup.md - Power management guide
• Bluetooth-Setup.md - Bluetooth setup and troubleshooting
• Dotfiles-Management.md - Complete chezmoi guide

Script Documentation

• scripts/wifi-setup/README.md - WiFi setup tool
• scripts/bluetooth-setup/README.md - Bluetooth setup tool
• scripts/audio-setup/README.md - Audio setup tool
• scripts/monitor-setup/README.md - Monitor setup tool
• scripts/battery-setup/README.md - Battery conservation tool

Emergency Recovery

If the system becomes unbootable:

1. Boot from Gentoo LiveCD/USB
2. Mount root filesystem: mount /dev/sdXY /mnt/gentoo
3. Chroot: chroot /mnt/gentoo /bin/bash
4. Source profile: source /etc/profile
5. Fix issue (kernel, config, etc.)
6. Exit chroot and reboot

Backup Restoration

If you need to restore from backup:

# List available backups on NAS
ssh alexander@192.168.2.171 "ls -la /mnt/ssd-pool-a/backups/lenovo-gentoo/"

# Restore specific backup
rsync -avz --progress \
  alexander@192.168.2.171:/mnt/ssd-pool-a/backups/lenovo-gentoo/YYYY-MM-DD/ \
  /restore-location/

See Backup-Setup.md for complete restoration procedures.