hops/TROUBLESHOOTING.md

HOPS Troubleshooting Guide

This document provides solutions to common issues encountered when installing and running HOPS.

Docker Repository Issues

Linux Mint Docker Repository Error

Symptoms:

E: The repository 'https://download.docker.com/linux/ubuntu xia Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.

Root Cause: Linux Mint uses its own codenames (e.g., "xia", "vera", "vanessa") that don't exist in Docker's Ubuntu repositories. Docker only supports Ubuntu codenames like "noble", "jammy", "focal".

Solution: This issue has been resolved in HOPS v3.3.0+. The system now automatically detects the correct Ubuntu codename for Linux Mint installations using UBUNTU_CODENAME from /etc/os-release.

Manual Fix (if needed):

1. Clean existing Docker repositories:

   sudo rm -f /etc/apt/sources.list.d/docker*
   sudo rm -f /etc/apt/sources.list.d/*docker*
   sudo rm -f /usr/share/keyrings/docker*
   sudo rm -f /etc/apt/keyrings/docker*
   sudo apt clean
   

2. Verify Ubuntu codename detection:

   grep '^UBUNTU_CODENAME=' /etc/os-release
   # Should return: UBUNTU_CODENAME=noble (for Linux Mint 22.x)
   

3. Update HOPS to latest version:

   cd ~/hops
   git pull
   sudo ./hops --update
   

Docker Installation Fails

Symptoms:

• Package 'docker-ce' has no installation candidate
• Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Solutions:

1. Check Docker service status:

   sudo systemctl status docker
   sudo systemctl status docker.socket
   

2. Fix missing Docker group:

   sudo groupadd docker
   sudo usermod -aG docker $USER
   sudo chown root:docker /var/run/docker.sock
   

3. Start Docker services:

   sudo systemctl start docker.socket
   sudo systemctl start docker
   sudo systemctl enable docker
   

4. Verify Docker installation:

   sudo docker --version
   sudo docker compose version
   sudo docker info
   

Directory and Permission Issues

Homelab Directory Not Found

Symptoms:

ERROR: Homelab directory not found: /root/hops

Root Cause: When running with sudo, the script may look for files in /root/hops instead of the user's home directory.

Solution: This issue has been resolved in HOPS v3.3.0+. The system now properly detects the original user's home directory when running with sudo.

Manual Workaround:

# Ensure you're in the correct directory
cd ~/hops
sudo ./hops

Permission Denied Errors

Symptoms:

• Permission denied accessing Docker socket
• Cannot create directories in /opt/appdata

Solutions:

1. Fix Docker permissions:

   sudo usermod -aG docker $USER
   # Log out and log back in, or run:
   newgrp docker
   

2. Fix directory permissions:

   sudo chown -R $USER:$USER ~/hops
   sudo chmod -R 755 ~/hops
   

Service Access Issues

Cannot Access Service Web UI

Symptoms:

• Service shows as running but web UI is not accessible
• Connection refused errors

Solutions:

1. Check container status:

   cd ~/hops
   sudo docker compose ps
   sudo docker compose logs [service-name]
   

2. Verify port availability:

   sudo netstat -tlnp | grep :8989  # For Sonarr
   sudo ss -tlnp | grep :8989       # Alternative command
   

3. Check firewall settings:

   sudo ufw status
   # If needed, allow ports:
   sudo ufw allow 8989  # Example for Sonarr
   

4. Restart services:

   cd ~/hops
   sudo docker compose restart [service-name]
   

Network Issues

Docker Network Creation Fails

Symptoms:

• Error response from daemon: network with name [network] already exists
• Network connectivity issues between containers

Solutions:

1. List existing networks:

   sudo docker network ls
   

2. Remove conflicting networks:

   sudo docker network rm traefik homelab
   

3. Recreate networks:

   cd ~/hops
   sudo docker compose up -d
   

System Requirements

Insufficient Resources

Symptoms:

• Services randomly stopping
• Out of memory errors
• Slow performance

Solutions:

1. Check system resources:

   free -h    # Memory usage
   df -h      # Disk usage
   top        # CPU and memory usage
   

2. Minimum requirements:

   • RAM: 2GB minimum, 4GB+ recommended
   • Disk: 10GB minimum, 50GB+ recommended for media
   • CPU: 2 cores minimum

3. Optimize services:

   • Disable unnecessary services
   • Adjust container resource limits
   • Use external storage for media files

Getting Help

Log Files

Check HOPS log files for detailed error information:

Linux:

sudo tail -f /var/log/hops/hops-main-*.log

macOS:

sudo tail -f /usr/local/var/log/hops/hops-main-*.log

Docker Compose Logs

cd ~/hops
sudo docker compose logs -f [service-name]

System Information

When reporting issues, include:

# System information
lsb_release -a
uname -a
docker --version
docker compose version

# HOPS version
./hops --version

# Container status
cd ~/hops && sudo docker compose ps

Reporting Issues

1. Check this troubleshooting guide first
2. Search existing GitHub Issues
3. Create a new issue with:
   • Complete error messages
   • System information (above commands)
   • Steps to reproduce
   • Log file excerpts

Recovery Commands

Complete Reset

If HOPS installation is completely broken:

# Stop all containers
cd ~/hops && sudo docker compose down

# Remove containers and images (CAUTION: This removes all data)
sudo docker system prune -a --volumes

# Clean up repositories
sudo rm -f /etc/apt/sources.list.d/docker*
sudo apt clean

# Reinstall HOPS
cd ~/hops
git pull
sudo ./hops

Partial Reset

To reset only HOPS configuration:

# Stop services
cd ~/hops && sudo docker compose down

# Remove generated files
rm -f ~/hops/docker-compose.yml ~/hops/.env

# Restart HOPS
sudo ./hops

---

Version History

• v3.3.0+: Fixed Linux Mint Docker repository detection
• v3.2.0+: Added macOS support and improved error handling
• v3.1.0+: Initial multi-platform support

For the latest updates and fixes, always ensure you're running the latest version:

cd ~/hops
sudo ./hops --update