Tech Digest

Guide

Home Assistant "Unable to connect to Home Assistant" behind a reverse proxy

Because the proxy forwards ordinary HTTP but not the WebSocket upgrade, and the dashboard cannot run without it. We put Home Assistant 2026.10.4 behind six proxies, removed the upgrade from each, and recorded what the browser and the logs said.

Last reviewed

Why does Home Assistant say "Unable to connect to Home Assistant" behind a reverse proxy?

Your proxy is not forwarding the WebSocket upgrade. Logging in is plain HTTP, so it works. The dashboard then opens a WebSocket at /api/websocket, and that needs the Upgrade and Connection headers passed on. In Nginx Proxy Manager, turn on Websockets Support for the host; it is off by default. In nginx, add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";. In Apache, add upgrade=websocket to the ProxyPass line. Caddy, Traefik and Cloudflare Tunnel pass it by default.

Your proxy is passing ordinary web requests but not the WebSocket upgrade. The login page and the login itself are plain HTTP, so they work. The dashboard then opens one long-lived connection to /api/websocket, and the proxy turns that request into a normal one. Home Assistant refuses it, and the screen shows:

text
Unable to connect to Home Assistant.
Retrying in 60 seconds...

In Nginx Proxy Manager, open the proxy host and turn on Websockets Support. In plain nginx, add two lines to the location:

nginx
location / {
    proxy_pass http://homeassistant:8123;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

In Apache, add upgrade=websocket to the end of the ProxyPass line. Caddy, Traefik and Cloudflare Tunnel already pass the upgrade, so look for a second proxy in the path.

The terms this answer turns on#

A WebSocket is a connection that stays open so both sides can send messages at any time. Home Assistant's developer docs call its WebSocket API "the main API". The frontend and the companion apps use it "for nearly everything". Every state change on your dashboard arrives over it.

A WebSocket starts life as an HTTP request with two extra headers: Upgrade: websocket and Connection: Upgrade. The server agrees by answering 101 Switching Protocols. From then on the line carries WebSocket messages instead of HTTP.

Those two headers are hop-by-hop. The nginx docs explain that such headers are "not passed from a client to proxied server". A proxy removes them unless it is told to send them on. Home Assistant then sees an ordinary GET for /api/websocket and answers 400.

"Unable to connect to Home Assistant." is the frontend's text when that connection fails. The frontend code starts a 60-second countdown and then reloads the page. So the message comes back every minute until the proxy is fixed.

Is it this, or the 400 untrusted proxy?#

Both faults sit at the proxy and both involve a 400, so they get mixed up in threads. They look different from the first screen. We ran both against the same Home Assistant:

What you checkWebSocket upgrade missingProxy not trusted
Login pageLoads, login worksDoes not load; the page says 400: Bad Request
After login"Unable to connect to Home Assistant."You never get there
Home Assistant logNothing at the default levelERROR ... Received X-Forwarded-For header from an untrusted proxy 10.250.10.21
Proxy access log400 only on /api/websocket400 on every path
Body of the 400No WebSocket UPGRADE hdr: None400: Bad Request

The Home Assistant docs say requests from reverse proxies "are blocked" unless Trust X-Forwarded-For and Trusted proxies are set. If your symptoms match the right-hand column, Home Assistant 400 Bad Request behind a reverse proxy covers that fix. Fixing trust will not clear the left-hand column, and adding WebSocket headers will not clear the right.

What each proxy did with the upgrade removed#

We ran Home Assistant 2026.10.4 in Docker, with its proxy network already trusted. In front of it we put Nginx Proxy Manager 2.16.0, nginx 1.30.6, Apache 2.4.69, Caddy 2.11.7, Traefik 3.7.15 and a cloudflared 2026.10.7 quick tunnel. Headless Chromium 142 logged in through each one and loaded the dashboard. We recorded the handshake, the screen and the logs:

Proxy and settingHandshakeScreen after login
NPM, Websockets Support off400Unable to connect
NPM, Websockets Support on101Dashboard
nginx, no Upgrade or Connection line400Unable to connect
nginx, Upgrade line only400Unable to connect
nginx, both lines101Dashboard
Apache, plain ProxyPass400Unable to connect
Apache, ProxyPass ... upgrade=websocket101Dashboard
Apache, RewriteRule to ws://, no mod_proxy_wstunnel loaded101Dashboard
Caddy, plain reverse_proxy101Dashboard
Traefik, plain router and service101Dashboard
cloudflared quick tunnel, straight to Home Assistant101Dashboard

Every 400 row produced the same console line, with only the host name changing:

text
WebSocket connection to 'ws://ha-npm-off.test/api/websocket' failed: Error during WebSocket handshake: Unexpected response code: 400

Home Assistant's own log stayed empty in all of them. The refusal comes from aiohttp, the web server underneath, while it prepares the connection. Home Assistant's WebSocket handler does not log that error, and it logs new connections only at debug level. The proxy's access log is the place to look. NPM's showed 400 400 - GET http ha-npm-off.test "/api/websocket" next to a column of 200s for everything else.

The setting for each proxy#

Nginx Proxy Manager. The host template adds these three lines only when allow_websocket_upgrade is on:

nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_http_version 1.1;

In 2.16.0 a new proxy host starts with the toggle off, both in the web form and when created through the API without the field. Edit the host, tick Websockets Support, and save. NPM writes the lines into the host's config and reloads. Its main nginx.conf already sets proxy_http_version 1.1 for every host, so the missing piece is only the two headers.

nginx. Add proxy_set_header Upgrade $http_upgrade; and a Connection line. The nginx docs give two forms. One is the fixed value "upgrade". The other maps $http_upgrade to $connection_upgrade, so normal requests send close instead. Both are fine. The docs also say proxy_http_version 1.1 was only needed before version 1.29.7. On an older nginx, add it too.

Apache. Since 2.4.47, the mod_proxy docs say mod_proxy_http can handle the upgrade "end-to-end" with the upgrade parameter:

apache
ProxyPreserveHost On
ProxyPass / http://homeassistant:8123/ upgrade=websocket
ProxyPassReverse / http://homeassistant:8123/

The mod_proxy_wstunnel page now carries a deprecation note pointing to this. The wstunnel page itself still shows RewriteRule ^/?(.*) "ws://homeassistant:8123/$1" [P,L] behind two RewriteCond lines. On 2.4.69 that worked too, with mod_proxy_wstunnel not even loaded. What failed was a bare ProxyPass with neither.

Caddy. Its docs say reverse_proxy "also supports WebSocket connections" with no extra setting. Our plain one-line config connected first time. One catch: by default Caddy closes open WebSockets when its config is reloaded. The dashboard then reconnects by itself, so a short blip after a reload is expected.

Traefik. A plain router and service passed the upgrade with nothing added. Traefik's entry points have a 60-second read timeout that cuts off long uploads. It did not cut the WebSocket: one connection held for over two minutes, as it did through Apache.

Cloudflare Tunnel. Cloudflare's docs say it "supports proxied WebSocket connections without additional configuration". There is still a WebSockets toggle on the zone's Network page, so check it if the tunnel fails here. Through our quick tunnel the dashboard loaded on the first try. In each of two runs, of two and four minutes, the frontend opened a new WebSocket once, at 109 and 106 seconds. It logged in again by itself, and no error screen appeared. A tunnel that returns 502 instead is a different fault, read in Why Cloudflare Tunnel returns 502 Bad Gateway with cloudflared in Docker.

Test it from a shell#

You can check the handshake without a browser. Add --http1.1, or the test lies:

bash
curl -sS -i --http1.1 --max-time 4 \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  https://ha.example.com/api/websocket

A working proxy prints HTTP/1.1 101 Switching Protocols and then hangs until the timeout, which is correct. A broken one prints a 400 with No WebSocket UPGRADE hdr: None in the body. Without --http1.1, curl spoke HTTP/2 to our working Cloudflare tunnel and got HTTP/2 400 with that same body.

A short timeout looks different#

A proxy that cuts idle connections too soon does not cause this error screen. Home Assistant's server code sets a heartbeat of 55 seconds on each WebSocket. The frontend also sent its own {"type":"ping"} every 30 seconds in our lab and got a pong each time. So any proxy timeout over 30 seconds never fires. nginx's default is 60 seconds, per its docs.

We set proxy_read_timeout 20s to see what happens below that. nginx closed the WebSocket every 20 seconds. The frontend opened a new one within the same second, logged in again and carried on. The dashboard never showed the error. The only sign was a fresh 101 for /api/websocket in nginx's access log every 20 seconds. If you see that pattern, raise the timeout above 30 seconds.

A worked case: NPM on a NAS#

The thread most people land on starts this way. Nginx Proxy Manager runs in Docker on a Synology NAS. Home Assistant is on another machine at 192.168.1.36:8123. The poster has already set use_x_forwarded_for and trusted_proxies. The login page loads, the login is accepted, and then the screen says "Unable to connect to Home Assistant."

Walk through it. The login page loaded through the proxy, so trust is not the problem; an untrusted proxy would have got 400: Bad Request on that page. The poster notes that the Google Assistant integration works over the same domain. One reply points out that Google "does not connect in same manner", so it proves nothing about WebSockets.

Open the browser's developer console. Suppose it shows failed: Error during WebSocket handshake: Unexpected response code: 400 for wss://.../api/websocket. That names the WebSocket. Run the curl test above. A 400 with No WebSocket UPGRADE hdr: None says Home Assistant got the request without its Upgrade header.

Now open the proxy host in NPM. Websockets Support is unticked, because that is the default. Tick it and save. NPM adds the three lines to that host's config. Reload the dashboard. The curl test should now print 101 Switching Protocols, and the page should load.

Why the thread mixes two fixes#

That thread has no accepted answer. The fix came from later replies. On 27 February 2022, one user solved it by turning on WebSocket custom headers in the Synology reverse proxy. On 6 May 2022, another found the cause in NPM: "I missed the checkbox of Websockets support." Both drew thanks from readers with the same problem.

The other answer in the thread is the trusted_proxies block, and it also drew thanks. The trust settings fix the 400 fault, not this one. A thread that collects both faults collects both fixes, and that is why both keep circulating. Use the table near the top to pick yours.

When this answer stops applying#

We tested over plain HTTP between the browser and each proxy, except for the Cloudflare tunnel, which used HTTPS. A TLS-ending proxy handles the upgrade the same way, but our TLS check covered Cloudflare only. We did not test Apache before 2.4.47, HAProxy, Synology's built-in reverse proxy, the NGINX add-on on Home Assistant OS, or the companion apps. Home Assistant Cloud remote access does not go through your proxy at all. If the 101 comes back and the screen still fails, the cause is past the proxy. Look at the browser console for the next error, such as an auth failure, which Home Assistant "Login attempt or request with invalid authentication" reads line by line.

What to do next#

Check the login page first. If it loads, run the curl test with --http1.1 and fix the proxy setting above until you get a 101. If the login page shows 400: Bad Request, go to the trust settings instead. For the rest of the proxy setup and the other headers that go missing, see Reverse proxy and TLS. If you are still choosing how to reach Home Assistant from outside, Remote access without port forwarding weighs a proxy against a tunnel, and the Home Assistant profile lists its other upkeep.

Questions#

Why does the Home Assistant login page work but the dashboard does not?

The login page and the login itself are ordinary HTTP requests, and every proxy forwards those. Only after login does the frontend open its WebSocket at /api/websocket. That one request needs the Upgrade and Connection headers, which a proxy drops unless told to pass them. So a proxy can serve the whole login flow perfectly and still break everything after it. In our lab every broken setup showed the login form, then "Unable to connect to Home Assistant."

Does Cloudflare Tunnel need a WebSocket setting for Home Assistant?

Not by default. Cloudflare's documentation says it supports proxied WebSocket connections without extra configuration. Through a cloudflared quick tunnel, our dashboard connected with a 101 on the first try. In a four-minute run it reconnected once on its own, with no error screen. A zone does have a WebSockets toggle on the Network page of the Cloudflare dashboard. If someone switched it off, turn it back on. A proxy between cloudflared and Home Assistant still needs its own WebSocket setting.

Do I need mod_proxy_wstunnel for Home Assistant on Apache?

Not on Apache 2.4.47 or later. Since that release, mod_proxy_http handles the upgrade itself when ProxyPass carries upgrade=websocket. The wstunnel documentation now marks that module as deprecated. On Apache 2.4.69 with only mod_proxy and mod_proxy_http loaded, upgrade=websocket worked, and so did the older RewriteRule to ws://. A plain ProxyPass with neither got 400.

Why does Home Assistant log nothing when the WebSocket fails?

Without an Upgrade header, aiohttp, the web server underneath Home Assistant, refuses the handshake with 400 and the text No WebSocket UPGRADE hdr: None. Home Assistant's WebSocket handler does not log that refusal, and it logs new connections only at debug level. This one never became a connection. In every broken case in our lab, the Home Assistant log stayed empty at the default level. The proxy's access log is where it shows: a 400 for /api/websocket while every other path got 200.

What proxy timeout does Home Assistant need for WebSockets?

Anything above 30 seconds. The frontend sent {"type":"ping"} every 30 seconds in our lab and got a pong back, so the line was never idle for longer. nginx's default of 60 seconds, and NPM's 90, are fine. With proxy_read_timeout 20s, nginx cut the connection every 20 seconds and the frontend reconnected straight away. That shows up as a new 101 in the access log every 20 seconds, not as the error screen.

Why does curl get 400 from /api/websocket when the browser works?

Over HTTPS, curl picks HTTP/2 when the server offers it. Through our working Cloudflare tunnel, plain curl got HTTP/2 400 with the same No WebSocket UPGRADE hdr body a broken proxy gives. The same command with --http1.1 got 101 Switching Protocols, and Chromium connected fine through the same tunnel. So a 400 from curl without that flag proves nothing. Always add --http1.1 when you test the WebSocket with curl.

Sources#

Published . Last reviewed . Found something out of date? Tell us and we will fix it and log the change.