--- title: "Troubleshooting" description: "Look up GlassHome errors and fixes by symptom or message. Illegal instruction, container won't start, CORS, connection drops, and more." canonical: https://glasshome.app/docs/troubleshooting section: "Troubleshooting" updated: 2026-06-09 --- # Troubleshooting Find your symptom, follow the fix. If nothing matches, file a [bug report](/docs/bug-reports). ## Quick index - [Container or addon crashes on start with `signal 4` / illegal instruction](#illegal-instruction) - [Setup wizard rejects the HA URL](#bad-ha-url) - [Connected, but entities never load](#no-entities) - [Dashboard loads but blank / errors in browser console](#blank-ui) - [Remote-access tunnel won't connect](#tunnel) - [Widget install fails / shows "incompatible SDK"](#widget-sdk) - [Layout / theme reset after update](#data-loss) - [Widget shows "Unavailable"](#widget-unavailable) - [HA login loop / OAuth fails](#oauth-loop) - [Theme or background not applying](#theme-not-applying) ---

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](/docs/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](/docs/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](/docs/bug-reports) 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](/docs/connecting) 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](/docs/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](/docs/bug-reports).