GlassHome GlassHome
Skip to content

Updated

View Markdown Open in ChatGPT Open in Claude

Troubleshooting

Find your symptom, follow the fix. If nothing matches, file a bug report.

Quick index

Container crashes with “Illegal Instruction” (signal 4)

Symptoms

Container or addon dies instantly. Logs show signal 4, SIGILL, trap invalid opcode, or Illegal instruction.

Cause

CPU does not expose SSE4.2. GlassHome requires Intel Nehalem (2008+) or AMD Bulldozer (2011+). On modern hardware, the actual cause is almost always a hypervisor hiding instructions from the guest.

Fix: virtualized host

By default many hypervisors expose a Pentium 4 era CPU profile for compatibility. Switch the guest CPU to one that exposes the host’s real features.

Proxmox

  1. Shut down the VM running HA / GlassHome.
  2. Hardware > Processor > Type: change kvm64 to host.
  3. Start the VM.

In a Proxmox cluster: use x86-64-v3 instead of host to keep live-migration working between v3-capable nodes.

VMware ESXi / Workstation. Disable EVC, or raise the EVC baseline to one that includes SSE4.2.

Hyper-V. Disable processor compatibility mode on the VM.

VirtualBox. Enable Nested VT-x/AMD-V. Avoid legacy CPU profiles.

Fix: bare metal

If GlassHome runs directly on hardware (no hypervisor), the CPU itself is below the minimum. No software fix. Move to a Raspberry Pi 4/5 or any PC from the last decade.

Setup wizard rejects the HA URL

The URL must include protocol and the port HA actually serves on. Verify by opening it in a browser tab. If you can’t reach HA in your browser, the dashboard can’t either.

Common mistakes:

  • Missing http:// or https://.
  • Wrong port (HA’s UI port, not the API).
  • HTTPS on dashboard side but plain HTTP on HA (or vice versa). They must match.
  • localhost from inside a container points at the container, not your machine. Use the LAN IP or host.docker.internal.

See Connecting → Entering the URL.

Connected, but no entities load

  • The HA user you authorized as may have no entity permissions. Re-authorize with an admin user.
  • HA’s auth integration may be using a custom provider that strips refresh tokens. Confirm HA’s configuration.yaml doesn’t disable refresh tokens.
  • If entities load partially, you’ve likely hit an HA WS rate limit during initial load. Refresh.

Dashboard loads blank

Open browser devtools (F12) > Console. Look for red errors:

  • Failed to fetch dynamically imported module: a widget bundle 404’d. Likely an installed community widget was unpublished. Remove the widget from your layout.
  • SecurityError: Failed to construct WebSocket: HTTPS dashboard trying to reach HTTP HA, or vice versa. Match protocols.
  • Refused to connect: CSP violation. Usually means you’re proxying the dashboard and the proxy strips required headers. Bypass the proxy to confirm.

Remote-access tunnel won’t connect

Feature in progress

The built-in managed tunnel is still under active development and not yet available. These steps will apply once it ships.

  • Click Settings > Remote Access > Retry.
  • Confirm the host can reach *.cloudflareaccess.com and github.com (the cloudflared binary is fetched from GitHub Releases on first enable).
  • Logs: docker logs glasshome (or HA addon log). Look for cloudflared lines.

More: Remote Access.

Widget install fails with “incompatible SDK”

The widget was built against a newer @glasshome/widget-sdk than the dashboard supports. Update the dashboard (docker compose pull && docker compose up -d, or addon update). If you’re the widget author, lower the sdkVersion range in the manifest or publish a build against the older SDK.

Dashboards or theme disappeared after update

Data lives in the Docker volume glasshome_data (mounted at /data). If it was missing on restart, the dashboard initializes a fresh DB.

  • Confirm the volume is mounted: docker inspect glasshome | grep Mounts -A 10.
  • If you migrated hosts, copy /data from the old host before first start on the new one.
  • HA addon stores data in addon-managed storage. Re-installing the addon with “remove data” unchecked preserves dashboards.

If your data really is gone, file a bug report with logs from the failing start.

Widget shows “Unavailable”

The entity the widget is bound to is missing or has been renamed in Home Assistant.

  • Check the entity still exists in HA (Settings > Devices & Services > Entities).
  • If it was renamed or removed, open the widget’s config dialog in edit mode and rebind it to the correct entity.

HA login loop / OAuth fails

If you keep being redirected back to the HA login page or authorization never completes:

  • Confirm the HA URL you entered is reachable from the browser (not just from the server). Open it in a new tab.
  • Check that the URL uses the correct protocol (http:// vs https://). A mismatch causes silent CORS failures.
  • Make sure popups are not blocked. The OAuth flow opens in a popup or redirect depending on the browser.

See Connecting to Home Assistant for URL format requirements and common pitfalls.

Theme or background not applying

  • Hard-refresh the page (Ctrl+Shift+R / Cmd+Shift+R) to clear any cached assets.
  • Confirm you are applying the change in Settings > Theme and that the save completes (changes persist immediately; there is no separate save button).
  • If a custom theme or uploaded background is not showing, confirm the file format is supported and try re-uploading. Creating or editing custom themes and uploading backgrounds requires Pro; applying an existing custom theme does not.
  • If the issue persists after a refresh, check the browser console for errors and file a bug report.