Client IP

Home Assistant 400 Bad Request behind a reverse proxy

Every 400 that Home Assistant's forwarded.py can raise, the log line each one leaves, which address goes in Trusted proxies, and where the setting lives since 2026.8.

· 15 min read · How we verify this

Key points

  • Home Assistant answers 400 Bad Request when a request carries X-Forwarded-For and HA was not told to trust the machine that sent it. The fix is two settings: turn on Trust X-Forwarded-For and add the proxy to Trusted proxies.
  • Since Home Assistant 2026.8 both settings live in the UI, under Settings > System > Network > HTTP server. Your old http: block is imported once. After that, edits to configuration.yaml are ignored, and a repair says so.
  • The address to trust is the one HA prints in the log line: A request from a reverse proxy was received from X or from an untrusted proxy X. With Nginx Proxy Manager in Docker that is usually the NPM container or its network, not your server's LAN IP.
  • A network must be written as a network address: 192.168.1.0/24, not 192.168.1.50/24. The second form fails validation. For one machine, enter the bare address.
  • Four rarer 400s come from the headers themselves: an X-Forwarded-For entry that is not a bare IP (such as ip:port), an empty X-Forwarded-Proto item, a proto count that is neither 1 nor the X-Forwarded-For count, and an empty X-Forwarded-Host. Nginx Proxy Manager on its own triggers none of them.

Home Assistant returns 400 Bad Request because the request came through a proxy that HA has not been told to trust. The proxy adds an X-Forwarded-For header, and HA refuses that header from an unknown machine. The fix is two settings: turn on Trust X-Forwarded-For, and add the proxy's address to Trusted proxies. The address to add is the one HA prints in its own log line, which is the address the proxy connects from as HA sees it.

Where you set this depends on your version. Since Home Assistant 2026.8, both settings are in the UI, under Settings > System > Network > HTTP server. Before that, they were the use_x_forwarded_for and trusted_proxies keys under http: in configuration.yaml. The change matters because most answers online still say "add these two keys", and on a current install an http: block you add or edit after the upgrade is ignored.

Log line (logger homeassistant.components.http.forwarded)What it meansFix
A request from a reverse proxy was received from X, but your HTTP integration is not set-up for reverse proxiesTrust X-Forwarded-For is offTurn it on and add X to Trusted proxies
Received X-Forwarded-For header from an untrusted proxy XIt is on, but X is not in the listAdd X, or a network that contains X
Invalid IP address in X-Forwarded-For: ...An entry is not a bare IP address, for example 203.0.113.50:51234Make the proxy send bare addresses
Empty item received in X-Forward-Proto header: ...X-Forwarded-Proto is empty or has an empty item, such as https,Fix the header the proxy sends
Incorrect number of elements in X-Forward-Proto. Expected 1 or N, got MMore than one proto value, but not one per X-Forwarded-For entrySend one value, or one per hop
Empty value received in X-Forward-Host headerX-Forwarded-Host is present but its last value is emptySend a real host or no header
Too many headers for X-Forwarded-For: ... (2025.10 and older only)The header arrived as two separate linesUpgrade to 2025.11 or later

The "X-Forward-Proto" spelling is HA's own, in the code. Every row is explained below, with the code behind it.

What the terms mean here#

A reverse proxy is a server that takes requests from the internet and passes them on to Home Assistant. Nginx Proxy Manager, Caddy, Traefik and the NGINX add-on are common ones. The proxy usually handles HTTPS, and HA talks plain HTTP to the proxy.

Home Assistant sees the TCP connection from the proxy, not from the visitor. The machine on the other end of that connection is the peer, and behind a proxy the peer is always the proxy.

So the proxy passes the visitor's address along in a header. X-Forwarded-For is a comma-separated list of addresses, and each proxy adds the address it received the request from on the right. The X-Forwarded-For header explains the format in full.

Any client can send that header too, with any value, so HA must decide whose header to believe. A trusted proxy is a peer that HA lets set the visitor's address. Every other peer that sends the header gets a 400. That rule arrived in Home Assistant 2021.7 with PR #51839. The release notes say HA "will now block HTTP requests when a misconfigured reverse proxy" is detected.

How Home Assistant handles a forwarded request#

The code is short and lives in homeassistant/components/http/forwarded.py. The version on the dev branch matches the 2026.11.1 release line for line. On every request it does this:

  1. No X-Forwarded-For at all? It does nothing and the request goes through. This is why HA works fine on the LAN and fails only through the proxy.
  2. Request came through Home Assistant Cloud? It skips the check, since Cloud remote access uses a tunnel, not a reverse proxy.
  3. Trust X-Forwarded-For off? It logs the first error line in the table and returns 400.
  4. Peer not in Trusted proxies? It logs Received X-Forwarded-For header from an untrusted proxy and returns 400.
  5. Reads the list. It joins every X-Forwarded-For line, splits on commas and checks each entry with Python's ip_address(). One bad entry means 400.
  6. Walks from the right. It skips every entry that is itself in Trusted proxies, and the first entry that is not trusted becomes the client. If every entry is trusted, it takes the leftmost one.
  7. Checks X-Forwarded-Proto and X-Forwarded-Host if they are present. Those checks are rows four to six of the table.

Step 6 is the same right-to-left walk that configuring trusted proxies describes for nginx, Apache and the rest. Steps 3 and 4 are what make HA strict: most servers ignore a header from an untrusted peer, but HA refuses the whole request instead.

Where the setting lives: UI since 2026.8, YAML before#

In 2026.8, the HTTP integration moved from configuration.yaml to the UI. The docs say: "Before Home Assistant 2026.8, the HTTP integration was configured in configuration.yaml." The settings are now in the HTTP server section of Settings > System > Network, and the two you need are Trust X-Forwarded-For and Trusted proxies.

The move happens once. On the first start after the upgrade, config.py copies your http: block into storage, marks the move as done, and raises a repair titled "The HTTP YAML configuration is deprecated". From then on, HA reads only the stored settings. If an http: block is still in the file, it raises a second repair: "HTTP YAML configuration is ignored after migration".

That is the trap. Suppose you upgraded to 2026.8 or later, then followed an old guide, added trusted_proxies to configuration.yaml and restarted. Nothing changes and the 400 stays, because HA never reads the new lines. Open Settings > System > Repairs first, and if either repair is there, make the change in the UI.

Saving the HTTP server settings restarts Home Assistant, and after the restart an admin must confirm them. The docs say that if they are "not confirmed within 5 minutes", HA goes back to the old ones, and the code sets the same limit. So open HA in the browser after the restart, through the proxy or on the LAN, and confirm.

On 2026.7 and older, the YAML block is still the only place:

yaml
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.18.0.0/16

In that YAML schema the two keys are a pair: the code marks both as Inclusive in a group named proxy. Give one without the other and the http: block fails validation.

Which address goes in Trusted proxies#

Put in the address HA prints in the log. Both of the common lines end with it: received from X or untrusted proxy X. That X is the peer, the machine that opened the connection to HA, and it is the only value HA tests against your list.

This is where most fixes go wrong. People enter their server's LAN IP, the public IP or the visitor's IP, and none of those is the peer unless the proxy really connects from it. Here is who the peer usually is:

  • Proxy on another machine on your LAN. The peer is that machine's LAN address, such as 192.168.1.20.
  • Proxy on the same machine, no containers. The peer is the loopback address, 127.0.0.1 or ::1.
  • Nginx Proxy Manager, Caddy or Traefik in a Docker container. The peer is an address inside a Docker network, often a 172.x address, not the Docker host's LAN IP. docker network inspect <network> shows the subnet and each container's address.
  • The NGINX add-on on Home Assistant OS. The add-on's own docs give 172.30.33.0/24 for Trusted proxies. Their troubleshooting section says a 400 means "you are probably missing the trusted_proxies configuration option".

If HA shows an IPv6 address in the log, the proxy connected over IPv6. Add that address, because an IPv4 entry does not cover it.

A container's address can change when the container is recreated, while a Docker network's subnet usually does not. So for a proxy in Docker, trusting the network is sturdier than trusting one container. It also trusts every other container on that network, so keep the proxy on a network with nothing else you do not control.

Network entries must use the network address#

The HTTP docs put this in a box marked "Important": "When a network mask is provided, you must use the network address (for example, 192.168.1.0/24), not a host address (for example, 192.168.1.50/24)."

The code shows why. Both the YAML schema and the new storage schema pass each entry through Python's ip_network(), whose strict flag is on by default. Python's docs say that then, "if host bits are set in the supplied address", a ValueError is raised. 192.168.1.50/24 has host bits set, so the value is refused.

Three forms work:

  • A bare address, such as 172.18.0.2, which counts as a network of one.
  • An address with a full mask, such as 172.18.0.2/32 or ::1/128.
  • A real network address, such as 172.18.0.0/16 or 192.168.1.0/24.

The other four 400s, from the headers themselves#

These fire only after the peer is trusted, and they come from what the proxy sends, not from HA's settings.

An entry that is not a bare IP address. Each X-Forwarded-For entry goes through ip_address(), which takes 203.0.113.50 or 2001:db8::1. It does not take a port, as in 203.0.113.50:51234, or brackets around IPv6. Any such entry gives Invalid IP address in X-Forwarded-For and a 400, and a hostname or the word unknown fails the same way.

An empty proto item. If X-Forwarded-Proto holds an empty value, or a list like https, ,http, HA logs Empty item received in X-Forward-Proto header and returns 400.

A proto count that does not fit. HA accepts either one X-Forwarded-Proto value or exactly one value per X-Forwarded-For entry. Two proto values next to one address is a 400. That points to a second proxy that added a proto line instead of replacing the first one. Since 2025.11, HA joins repeated header lines into one list, so two lines count as two values.

An empty forwarded host. If X-Forwarded-Host is present, HA takes its last value, and if that is empty it logs Empty value received in X-Forward-Host header and returns 400. If the header is absent, HA keeps the request's own Host.

One older rule is gone. Up to 2025.10, a request with two X-Forwarded-For lines was refused with Too many headers for X-Forwarded-For, and the same applied to the proto and host headers. PR #154793, merged in October 2025, made HA join the lines instead. The 2025.10.4 code still has the old check, and 2025.11.0 does not.

Nginx Proxy Manager sends none of these by itself. Its proxy.conf sets X-Forwarded-For with nginx's $proxy_add_x_forwarded_for, which adds bare addresses. Its nginx.conf maps X-Forwarded-Proto to exactly one value, http or https, and it sends no X-Forwarded-Host. So with NPM alone, only the first two rows of the table apply. If you see the others, look for a second proxy in front, such as a CDN or a tunnel.

"Access from the proxy's own address is rejected" is not what the code does#

The 2021.7 release notes add a line that many forum posts repeat: "Access to Home Assistant from the same IP address as a trusted proxy will be rejected if the request is marked as forwarded." In the code that shipped, that is not what happens.

PR #52073 did add that rule to forwarded.py in June 2021: if every X-Forwarded-For entry was a trusted proxy, HA logged a warning and returned 400. Five days before 2021.7.0 shipped, PR #52388 took it back out. In its place, forwarded.py takes the leftmost entry, as in step 6 above, and that is still the code today.

The refusal moved to the trusted networks login provider, which lets listed devices log in without a password. In trusted_networks.py, a login from an address inside Trusted proxies fails with "Can't allow access from a proxy server", which is a failed login, not a 400.

This has one practical result. If you trust your whole LAN, 192.168.1.0/24, as proxies, no device on that LAN can use trusted networks login, because every LAN address is now a "proxy". Trust only the proxy's address or its Docker network.

Why the list should stay narrow#

Every address in Trusted proxies is one whose X-Forwarded-For entries HA skips, so a wide list moves the point where the walk stops.

Take NPM with $proxy_add_x_forwarded_for. A visitor at 203.0.113.50 sends a fake X-Forwarded-For: 10.0.0.9, and NPM passes on 10.0.0.9, 203.0.113.50. HA walks from the right, finds the public address untrusted and makes it the client. The fake entry is never reached, which is correct.

Now suppose the visitor is on your LAN and you trusted the whole LAN. Their real address is skipped as a "proxy", so the walk reaches their fake entry and takes it. HA's login ban and its logs now record an address the visitor chose. Client IP spoofing through proxies shows what else breaks when the trust line sits in the wrong place.

Worked case: Nginx Proxy Manager in Docker#

Take a common home setup. Home Assistant runs in a container on a server at 192.168.1.10, port 8123. Nginx Proxy Manager runs in another container on the same server, on a Docker network that, say, uses 172.18.0.0/16, and NPM has 172.18.0.2. A proxy host for ha.example.com forwards to HA, which is on 2026.11 and has never had an http: block. Walk a request through.

  1. A phone at 203.0.113.50 opens https://ha.example.com, and NPM ends the HTTPS session.
  2. NPM connects to HA. Per its proxy.conf, it sends X-Forwarded-For: 203.0.113.50, X-Forwarded-Proto: https, X-Forwarded-Scheme: https and X-Real-IP: 203.0.113.50. HA reads only the first two.
  3. HA sees X-Forwarded-For, and Trust X-Forwarded-For is off, the default. Suppose the log then reads A request from a reverse proxy was received from 172.18.0.2, but your HTTP integration is not set-up for reverse proxies. The phone gets 400: Bad Request.

The log has handed you the peer: 172.18.0.2. Now try the three usual fixes against it.

  • Trust X-Forwarded-For on, Trusted proxies 192.168.1.10. This is the server's LAN IP and the most common guess. The peer is still 172.18.0.2, which is not in the list. The log changes to Received X-Forwarded-For header from an untrusted proxy 172.18.0.2, and the phone still gets a 400.
  • Trusted proxies 172.18.0.2/16. The host bits are set, so ip_network() rejects it as invalid.
  • Trusted proxies 172.18.0.0/16, or just 172.18.0.2. Save, let HA restart and confirm within five minutes.

Run the same request again with the third setting.

  1. The peer 172.18.0.2 is inside 172.18.0.0/16, so the untrusted-proxy check passes.
  2. The list is 203.0.113.50, a valid address that is not trusted, so it becomes the client. HA's logs and login ban now use the phone's address.
  3. X-Forwarded-Proto has one value, https, and one value is always allowed, so HA records the scheme as https.
  4. There is no X-Forwarded-Host, so HA keeps the Host that NPM passed on, ha.example.com, and the request goes through.

Had this install been on 2026.7, the third fix would be the YAML block shown earlier. The address logic is identical.

If the login page now loads but the dashboard says it cannot connect, that is a different fault. HA's frontend needs a live WebSocket connection through the proxy, which in NPM is the Websockets Support switch on the proxy host. WebSockets through a reverse proxy covers the headers it adds. If NPM shows 502 Bad Gateway instead of HA's 400, the request never reached HA. Nginx Proxy Manager 502 Bad Gateway maps each form field to the error it leaves.

Where this answer stops applying#

The rules here come from the source of Home Assistant 2026.11.1, which matches the dev branch for forwarded.py, and from the HTTP integration docs. The YAML-to-UI move is in the 2026.8.0 code and later, the repeated-header change is in 2025.11.0, and the trusted networks rule dates from PR #52388 in 2021. Nothing on this page was run against a live Home Assistant. The Docker addresses in the worked case are examples, and your peer is whatever HA prints in its log. The Nginx Proxy Manager headers come from its current develop source, and older releases may differ. Caddy, Traefik and cloud tunnels each send their own headers, so check them against the table. This page covers only the 400 from the forwarded-header check, not HA's login bans, an HTTPS mismatch between proxy and HA, or what your proxy does with the client address before HA sees it. For servers other than HA, why uvicorn or gunicorn shows 127.0.0.1 or 172.17.0.1 as the client IP shows the same trust question in Python's own servers.

Frequently asked questions#

Why does Home Assistant return 400 Bad Request through my reverse proxy?#

The proxy adds an X-Forwarded-For header, and HA refuses that header from any machine it does not trust. Turn on Trust X-Forwarded-For and add the proxy's address, as shown in HA's log, to Trusted proxies. On 2026.8 and later both are in Settings > System > Network > HTTP server.

I added trusted_proxies to configuration.yaml and nothing changed. Why?#

On 2026.8 and later, HA imports the http: block once and then ignores it, so edits made after that first start are never read. Check Settings > System > Repairs for "HTTP YAML configuration is ignored after migration", then make the change in the UI and remove the YAML block.

What IP address do I put in trusted_proxies for Nginx Proxy Manager in Docker?#

The address in HA's log line, which is the address NPM connects from. With NPM in a container, that is usually NPM's address on its Docker network, or that network as a subnet such as 172.18.0.0/16, not the Docker host's LAN IP. docker network inspect shows the real values.

Why is 192.168.1.50/24 rejected in Trusted proxies?#

HA checks each entry with Python's ip_network() in strict mode, and a value with host bits set, like 192.168.1.50/24, raises an error. Write the network address, 192.168.1.0/24, or the single address 192.168.1.50.

What does "Received X-Forwarded-For header from an untrusted proxy" mean?#

Trust X-Forwarded-For is on, but the address at the end of the line is not in Trusted proxies. Add that exact address, or a network written in network-address form that contains it.

Does Home Assistant reject requests from the proxy's own IP?#

Not with a 400. A 2021.7 release note says so, but PR #52388 removed that rule before 2021.7.0 shipped. If every X-Forwarded-For entry is trusted, HA takes the leftmost one. What HA does refuse is a trusted networks login from an address inside Trusted proxies.

Do I need these settings for Home Assistant Cloud (Nabu Casa)?#

No. The HTTP docs say these settings "have no effect on cloud connections", and the code skips the forwarded check for Cloud requests.

Primary sources#

Every normative claim on this page is checked against the specification or the vendor documentation listed here. Where behaviour is version dependent, the version is named in the text.

  1. Home Assistant core, homeassistant/components/http/forwarded.py (dev; identical in 2026.11.1)
  2. Home Assistant core 2026.11.1, homeassistant/components/http/__init__.py (YAML schema, Inclusive pair, ip_network)
  3. Home Assistant core 2026.11.1, homeassistant/components/http/config.py (YAML migration, storage schema, 5 minute revert)
  4. Home Assistant core 2026.11.1, homeassistant/components/http/strings.json (repair issue texts)
  5. Home Assistant core, homeassistant/auth/providers/trusted_networks.py ("Can't allow access from a proxy server")
  6. Home Assistant core 2025.10.4, forwarded.py ("Too many headers" rejection)
  7. Home Assistant documentation, HTTP integration
  8. Home Assistant 2021.7 release notes, backward-incompatible changes
  9. Home Assistant core PR #51839: Raise bad request when receiving HTTP request from untrusted proxy
  10. Home Assistant core PR #52073: Reject requests from the proxy itself
  11. Home Assistant core PR #52388: Reject trusted network access from proxies
  12. Home Assistant core PR #154793: Fix incorrect forward header handling
  13. Home Assistant add-ons, NGINX Home Assistant SSL proxy documentation
  14. Nginx Proxy Manager source, docker/rootfs/etc/nginx/conf.d/include/proxy.conf
  15. Nginx Proxy Manager source, docker/rootfs/etc/nginx/nginx.conf (X-Forwarded-Proto map)
  16. Python documentation, ipaddress.ip_network (strict)

Found something wrong, or behaviour that differs on your version? Report it with the version number and a primary source. Anything substantive is fixed in the page and logged on the corrections page. See editorial standards for how pages are researched, sourced and reviewed.

More in client ip and forwarding headers#