Skip to content

Troubleshooting

Common issues and how to resolve them.

Can't access the web interface

Symptom: Browser can't reach https://halos.local/.

Possible causes and solutions:

  1. No internet on first boot: Container images are downloaded on first boot. Without internet, only Cockpit on port 9090 works. Connect via Ethernet or use the AP image to configure WiFi first — see First Boot.

  2. Not enough time: Core containers take 2–3 minutes to download and start after boot. Wait and try again.

  3. Hostname not resolving: mDNS (.local) resolution depends on your client device and network. Try:

    • Accessing by IP address instead (check your router's DHCP client list)
    • Using a different device or browser
    • On Windows, ensure the Bonjour service is running

  4. Not on the same network: Your device must be on the same local network as the Raspberry Pi. If using WiFi, ensure you're connected to the right network.

  5. Try Cockpit directly: Cockpit runs independently on port 9090 and doesn't depend on Traefik or Authelia. Try https://halos.local:9090/ — if this works, the issue is with the reverse proxy containers.

Certificate warnings

Symptom: Browser shows a security warning when accessing any HaLOS URL.

This is expected behavior. HaLOS uses self-signed certificates because automatic certificates (Let's Encrypt) aren't possible on local .local networks.

Accept the certificate warning for each port as you encounter it — the same certificate covers all ports, but browsers treat each port as a separate origin.

See First Boot — Certificate warning for browser-specific instructions.

Container app store is empty

Symptom: The Container Apps section in Cockpit shows no applications.

Solution: Run a system update first:

sudo apt update && sudo apt upgrade

This downloads the latest package lists from the Hat Labs repository. After updating, the container store should show available apps.

App not showing on the dashboard

Symptom: You installed an app but it doesn't appear on the Homarr dashboard.

Check these in order:

  1. Is the container running? Check via Cockpit → Services or: 

    sudo docker ps

  2. Wait for the adapter: The homarr-container-adapter syncs containers to the dashboard periodically. Give it a minute after install.

  3. Check adapter logs: 

    sudo journalctl -u homarr-container-adapter -f

  4. Restart the adapter: 

    sudo systemctl restart homarr-container-adapter

WiFi not connecting

Symptom: Can't connect to a WiFi network through Cockpit.

  1. Open Cockpit → Networking and check the WiFi interface status.
  2. Verify the WiFi credentials are correct.
  3. Check Cockpit → Logs for NetworkManager errors.
  4. If using an AP image, the device may be in AP mode. Switch to client mode through Cockpit NetworkManager.
  5. As a fallback, connect via Ethernet and configure WiFi from the wired connection.

SSH access

Headless images: SSH is enabled by default. Connect with:

ssh pi@halos.local

Default password: halos

Desktop images: SSH is disabled by default. Enable it via the Cockpit terminal or by connecting a keyboard and monitor:

sudo systemctl enable --now ssh

Changed hostname, can't connect

Symptom: After changing the hostname, halos.local no longer works.

The old .local hostname stops resolving once the hostname is changed. Use the new hostname instead:

https://<new-hostname>.local/

If you've forgotten the new hostname, find the device by:

  • Checking your router's DHCP client list for the device's IP address
  • Connecting a monitor and keyboard to see the login prompt (which shows the hostname)
  • Scanning the network: ping -c1 halos.local (if you haven't changed it) or use a network scanner

HALPI2 drops to initramfs on CM5 eMMC

Symptom: After flashing a HALPI2 image to a Compute Module 5's eMMC, the system drops to an initramfs BusyBox prompt instead of booting normally. The same image works fine when flashed to an NVMe SSD.

Cause: HALPI2 images disable the SD card interface (dtparam=sd=off in config.txt) to avoid a known shutdown delay. On CM5, the eMMC uses the same controller, so disabling it prevents the kernel from finding the root filesystem.

Solution: After flashing and before booting, mount the boot partition on your computer and edit config.txt:

  1. Find the line dtparam=sd=off (near the end of the file).
  2. Comment it out by adding a # prefix: 
    #dtparam=sd=off
  3. Save, unmount, and boot.

Note

This only affects CM5 eMMC. HALPI2 units with NVMe SSDs are not affected.

Containers not starting

Symptom: Services show as failed or containers aren't running.

  1. Check the service status: 

    sudo systemctl status <service-name>.service

  2. Check Docker: 

    sudo docker ps -a
sudo docker logs <container-name>

  3. Check disk space — containers need room for images: 

    df -h

  4. Check if Docker is running: 

    sudo systemctl status docker

Getting help