troubleshooting Guide

Quick solutions to common Pimeleon issues.

Common Issues

Boot and Startup Issues

Boot Failures - Problems during system startup:

• Pi won't boot or shows rainbow screen
• Red power LED behavior
• Kernel panic or boot loops
• SD card detection failures

Network Connectivity

Network Issues - Problems with internet or LAN connectivity:

• No internet access
• DHCP not working
• DNS resolution failures
• WiFi access point not broadcasting
• Cannot reach Pimeleon interface

Performance Issues

Performance Problems - Slow network or system performance:

• Slow internet speeds
• High CPU usage
• Memory exhaustion
• SD card I/O bottlenecks
• Thermal throttling

Quick Diagnostics

Check System Status

# SSH into Pimeleon
ssh pi@pimeleon.local

# Check system resources
top

# Check network interfaces
ip addr show

# Check routing
ip route show

# Check firewall rules
sudo nft list ruleset

Check Service Status

# Check critical services
systemctl status dnsmasq
systemctl status pihole-FTL
systemctl status dnscrypt-proxy
systemctl status privoxy

Check Logs

# System logs
journalctl -xe

# DNS logs
tail -f /var/log/pihole/pihole.log

# DNSCrypt logs
journalctl -u dnscrypt-proxy -f

Emergency Recovery

If Pimeleon is completely unresponsive:

1. Power cycle - Disconnect power for 30 seconds, reconnect
2. Check SD card - Remove and re-seat the microSD card
3. Restore backup - Flash previous working configuration

Getting Help

If you cannot resolve the issue:

1. Check documentation - Review relevant service documentation
2. Search logs - Look for error messages in system logs
3. Community support - Ask in community forums
4. Issue tracker - Report bugs on GitHub/GitLab

Related Documentation

• Boot Issues - Detailed boot troubleshooting