Skip to content
GlassHome
Dash pages

Updated

View MarkdownOpen in ChatGPTOpen in Claude

Troubleshooting

Find your symptom, follow the fix. If nothing matches, copy diagnostics from Settings > General and 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 so live migration keeps 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 rejects the Home Assistant address

The welcome screen looks for Home Assistant on your network by itself. When it can’t find it, it asks for the address. That address 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 (the port HA’s web interface uses).
  • HTTPS on dashboard side but plain HTTP on HA (or vice versa). They must match.
  • localhost from inside a container points at the container itself. Use the LAN IP or host.docker.internal to reach your machine.

See Connecting: when you type the address.

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.

Can’t reach the dashboard from outside home

  • Page loads, then stays empty: your proxy is not forwarding WebSocket upgrades. Pass Upgrade and Connection through.
  • Sign-in is refused: the address isn’t declared. Add it under Settings > Remote access (household admin), on the local address if you’re locked out.
  • “Public addresses need GlassHome Pro”: the hostname resolves to a public IP. Addresses that resolve to a home IP stay free.
  • Home Assistant sign-in fails while away: expected. Use a Hub account, Name and password, or Code from a phone.

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 are the widget’s author, see Widget Dev → Troubleshooting.

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 opens in your browser. 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.
  • To use a preset or a theme already on your Dash, choose Use in Settings > Theme. It applies straight away.
  • A theme made in the creator studio reaches your home only when you choose Save and use. Until then the changes stay in the studio, and Cancel puts your home back as it was.
  • If a custom theme or uploaded background is not showing, confirm the file format is supported and try re-uploading. Saving a theme and uploading pictures need Pro; applying a theme already on your Dash does not.
  • If the issue persists after a refresh, check the browser console for errors and file a bug report.

Camera shows no picture

A camera’s Stream Engine setting picks how its video arrives: Auto, WebRTC, HLS, MJPEG or Snapshot. Auto tries the best one first. When the engine you chose cannot start, the camera falls to a lighter one on its own, in this order: WebRTC, then HLS, then MJPEG, then Snapshot, which shows a still picture that refreshes.

If the picture stays missing:

  • Hold the camera widget in edit mode to open its settings, and set Stream Engine to Auto.
  • For Snapshot, Snapshot Refresh (seconds) sets how often the still picture updates.
  • Open the camera in Home Assistant. If it shows no picture there, the problem sits with the camera or its integration.