Homarr: Dashboard Not Loading — Fix

The Problem

Your Homarr dashboard won’t load, shows a blank white page, widgets display errors instead of data, or the page partially loads but services show as offline even though they’re running.

The Cause

Homarr issues typically fall into three categories: container startup failures (port conflicts, volume permissions), networking problems (Homarr can’t reach your other containers), or browser-side issues (cache, CORS with reverse proxy). Version mismatches between Homarr v0.x and v1.x can also cause blank pages if your config format doesn’t match the installed version.

The Fix

Method 1: Check Container Health

Verify Homarr is actually running and healthy:

docker compose logs homarr

Look for:

• Port conflict: Error: listen EADDRINUSE :::7575 — another service is using port 7575. Change the host port in your Docker Compose file.
• Permission errors: EACCES: permission denied on the data directory. Fix with: chown -R 1000:1000 ./homarr-data
• Database migration errors: Common when upgrading from v0.x to v1.x. Check the migration guide.

Method 2: Fix Widget Connections

Widgets show “Unable to connect” or “Error” even though services are running.

Cause: Homarr connects to services from inside the Docker network. If you entered http://localhost:8080 as a service URL, Homarr looks for port 8080 on its own container, not your host.

Fix: Use the container name or Docker network IP instead:

# Find your container's network name
docker network ls

# Find the IP of the service you want to monitor
docker inspect <container-name> | grep IPAddress

In Homarr widget settings, use http://<container-name>:<port> instead of http://localhost:<port>. Both containers must be on the same Docker network.

Method 3: Fix Blank Page Behind Reverse Proxy

Symptom: Homarr loads on http://server-ip:7575 but shows a blank page through your reverse proxy.

Fix: Ensure your reverse proxy passes WebSocket connections. For Nginx Proxy Manager, enable “WebSockets Support” in the proxy host settings. For Nginx manually:

location / {
    proxy_pass http://homarr:7575;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Method 4: Clear Browser Cache

If Homarr loads partially or shows stale content after an upgrade:

1. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
2. Clear site data: Open DevTools → Application → Storage → Clear site data
3. Try an incognito/private window

Method 5: Fix Volume Permissions (Homarr v1.x)

Homarr v1.x changed its internal user from root to a non-root user (UID 1000). If upgrading from v0.x:

# Stop Homarr
docker compose down

# Fix permissions on the data directory
sudo chown -R 1000:1000 ./homarr-data

# Restart
docker compose up -d

Prevention

• Pin your Homarr version tag — don’t use :latest. Pin to a specific version (e.g., ghcr.io/homarr-dev/homarr:0.15.10) so upgrades are intentional.
• Use container names for widget URLs — never localhost. Put Homarr and your services on the same Docker network.
• Back up your data directory before upgrading — Homarr stores its configuration and database there.
• Check the changelog before upgrading across major versions — v0.x → v1.x requires a database migration.

Related

• How to Self-Host Homarr
• Best Self-Hosted Dashboards
• Homarr vs Homepage
• Docker Compose Basics
• Reverse Proxy Setup