Home Assistant / Troubleshooting
Home Assistant Blocks Requests from a Reverse Proxy Until It Is Trusted
Confirm direct access works, verify that Trust X-Forwarded-For and the proxy address are set as a network CIDR, then save and confirm the restart within the Home Assistant 2026.8 revert window.
The Home Assistant HTTP integration documentation states that requests from reverse proxies are blocked if the reverse-proxy settings are not configured. The settings involved are Trust X-Forwarded-For and Trusted proxies, with Trusted proxies taking IP addresses or CIDR networks.[1]
The Home Assistant 2026.8 release notes describe the web-server settings as a screen in the UI under Settings, System, Network, which also holds the trusted proxies setting for the setups that need them, and note that the first time Home Assistant starts after upgrading, an existing configuration.yaml http: block is imported into the UI.[2]
Applicability
- Products
- Home Assistant
- Scope
- For Home Assistant served behind a traditional reverse proxy on a trusted network, where the proxy reaches Home Assistant and a direct local request succeeds but a request through the proxy is blocked. As of Home Assistant 2026.8 the relevant web-server settings (port, listen address, trusted proxies) live in the UI under Settings, System, Network, and the historical configuration.yaml http: block is imported into the UI on the first start after the upgrade. This page does not cover Home Assistant Cloud remote access, which uses a secure tunnel and is not affected by these settings, nor a TLS, DNS, or routing failure at the reverse proxy itself.[1][2]
- Last verified
Symptoms
- Home Assistant is reachable on its local port and a direct request returns the normal interface, but a request arriving through the reverse proxy is blocked. The HTTP integration documentation describes the response as requests from reverse proxies being blocked when the relevant settings are not set. A TLS failure at the reverse proxy, a DNS failure, an upstream routing failure, an authentication failure, or a Home Assistant Cloud remote-access problem is a different observation.[1]
Quick diagnosis
Compare a direct request with a proxied request before changing anything. A proxy-trust issue is different from TLS, DNS, routing, authentication, or Cloud remote access.
Confirm direct local access works
Open Home Assistant on its local port from the same network the reverse proxy leaves. A successful direct response isolates the failure to the proxy path. A failed direct response means the issue is not the proxy trust setting.[1]
Confirm the reverse proxy reaches Home Assistant
Verify that the reverse proxy upstream points to the Home Assistant host and port, and that the proxy itself is healthy. A failure to reach Home Assistant at the proxy is a proxy or network problem and is not diagnosed by this page. The HTTP integration documentation notes that the Trust X-Forwarded-For and Trusted proxies settings only apply when Home Assistant is behind a traditional reverse proxy such as NGINX, Caddy, Traefik, or HAProxy.[1]
Locate the current web-server settings
Open Settings, System, Network, and find the HTTP server section. The Home Assistant 2026.8 release notes describe the web-server settings as a screen in the UI; the integration documentation places the same settings on the HTTP integration page for reference. The historical configuration.yaml http: block is imported into the UI on the first start after the upgrade and can be removed from YAML after the import.[1][2]
Do not change other security settings while diagnosing
Do not disable IP banning, change the login attempts limit, or expose the admin interface to a broader network while investigating. The HTTP integration documentation describes IP banning and login attempts as separate, optional security settings; this page is about the trust boundary for the reverse proxy only.[1]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Safe diagnostic guidanceIs Home Assistant behind a traditional reverse proxy, not Home Assistant Cloud?
The HTTP integration documentation states that Trust X-Forwarded-For and Trusted proxies only apply when Home Assistant is behind a traditional reverse proxy such as NGINX, Caddy, Traefik, or HAProxy, and have no effect on Home Assistant Cloud connections.[1]
Read the complete diagnostic tree without using the controls
- Is Home Assistant behind a traditional reverse proxy, not Home Assistant Cloud?
The HTTP integration documentation states that Trust X-Forwarded-For and Trusted proxies only apply when Home Assistant is behind a traditional reverse proxy such as NGINX, Caddy, Traefik, or HAProxy, and have no effect on Home Assistant Cloud connections.[1]
- Yes, behind a traditional reverse proxy → Are Trust X-Forwarded-For and the proxy address in Trusted proxies both set?
- Home Assistant Cloud is in use → Not a proxy-trust problem
- Direct connection, no reverse proxy → Not a proxy-trust problem
- Deployment is unclear → Investigate the actual environment or response
- Are Trust X-Forwarded-For and the proxy address in Trusted proxies both set?
The HTTP integration documentation states that requests from reverse proxies are blocked if these options are not set. Inspect the HTTP server section in the UI under Settings, System, Network; the 2026.8 release notes place the trusted proxies setting on the same screen.[1][2]
- Yes, both are set → Is the trusted entry a network address (for example, 192.168.1.0/24) and not a host address?
- No, one or both are not set → Enable Trust X-Forwarded-For and add the proxy to Trusted proxies
- Cannot determine the current values → Investigate the actual environment or response
- Is the trusted entry a network address (for example, 192.168.1.0/24) and not a host address?
The HTTP integration documentation requires the network address when a mask is provided, not a host address.[1]
- Yes, network address is used → Settings are in place; the proxy is trusted
- No, a host address is used → Replace the host address with a network address
- Address form is unclear → Investigate the actual environment or response
- Enable Trust X-Forwarded-For and add the proxy to Trusted proxies
Enable Trust X-Forwarded-For in the HTTP server section, add the reverse proxy address or the proxy source network as a CIDR network address, and save. The HTTP integration documentation states that the settings only apply behind a traditional reverse proxy.[1]
- Replace the host address with a network address
Edit the Trusted proxies entry so the mask is on the network address, not a host address, then save. The HTTP integration documentation requires the network address when a mask is provided.[1]
- Settings are in place; the proxy is trusted
After the restart that follows the save, the proxied request should succeed. If the new settings cannot be applied or the proxied request still fails, Home Assistant automatically returns to the previous settings after five minutes per the 2026.8 release notes.[1][2]
- Not a proxy-trust problem
If the deployment is direct or uses Home Assistant Cloud, Trust X-Forwarded-For and Trusted proxies are not the relevant controls. The HTTP integration documentation states that the settings only apply behind a traditional reverse proxy and have no effect on Home Assistant Cloud connections.[1]
- Investigate the actual environment or response
Record the current Trust X-Forwarded-For and Trusted proxies values, the reverse proxy software, the proxy source IP, and the response observed through the proxy. A TLS failure at the proxy, a DNS failure, an authentication failure, or a deployment on Home Assistant Cloud is a separate investigation. This page does not authorize disabling authentication or TLS validation.[1]
Detailed diagnosis
1. Read the current Trust X-Forwarded-For and Trusted proxies values
Inspect the HTTP server section in the UI. The HTTP integration documentation states that requests from reverse proxies are blocked if Trust X-Forwarded-For and the proxy entry in Trusted proxies are not set. A historical configuration.yaml http: block must be imported into the UI before this step; the 2026.8 release notes describe the import behaviour.[1][2]
2. Confirm the trusted entry is a network address
Compare the configured Trusted proxies entry with the source network the proxy actually uses. The HTTP integration documentation states that when a network mask is provided, the network address must be used (for example, 192.168.1.0/24), not a host address (for example, 192.168.1.50/24). A host address in a CIDR slot is not the documented value and will not match the proxy source as intended.[1]
3. Confirm the deployment matches the supported scope
Confirm that the deployment uses a traditional reverse proxy, not Home Assistant Cloud. The HTTP integration documentation states that Trust X-Forwarded-For and Trusted proxies only apply when Home Assistant is behind a traditional reverse proxy such as NGINX, Caddy, Traefik, or HAProxy, and that the settings have no effect on Home Assistant Cloud connections.[1]
4. Note that saving the HTTP server settings restarts Home Assistant
The HTTP integration documentation states that saving HTTP server settings restarts Home Assistant, and the 2026.8 release notes describe the same screen as waiting for an administrator to confirm the new settings within five minutes, after which Home Assistant automatically returns to the previous settings and restarts. Plan for the restart window before saving.[1][2]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
Trust X-Forwarded-For or Trusted proxies is not set
The HTTP integration documentation states that requests from reverse proxies are blocked if these options are not set. With no trusted entry, Home Assistant refuses the proxied request.[1]
How to check: Open the HTTP server section and confirm that Trust X-Forwarded-For is enabled and the proxy is listed in Trusted proxies.[1]
The trusted entry is a host address, not a network address
The HTTP integration documentation requires a network address when a mask is provided, not a host address. A host address will not match the proxy source network and the proxied request will continue to be blocked.[1]
How to check: Compare the entry with the source network the proxy actually uses and replace the host address with the network address.[1]
The deployment uses Home Assistant Cloud, not a traditional reverse proxy
The HTTP integration documentation states that Trust X-Forwarded-For and Trusted proxies only apply when Home Assistant is behind a traditional reverse proxy. Home Assistant Cloud uses a secure tunnel; these settings have no effect on cloud connections and do not need to be configured for remote access through Cloud.[1]
How to check: If remote access is via Home Assistant Cloud, the proxy-trust settings are not the right control; review the Cloud integration instead.[1]
Next actions and procedure boundaries
Enable Trust X-Forwarded-For and add the proxy to Trusted proxies
Open the HTTP server section, enable Trust X-Forwarded-For, and add the reverse proxy address or the proxy source network as a CIDR network address (for example, 192.168.1.0/24), not a host address. Save the settings. The HTTP integration documentation states that the settings have no effect on Home Assistant Cloud connections; do not use 0.0.0.0/0 as a workaround.[1]
Before changing anything
- Risk
- Saving the HTTP server settings restarts Home Assistant; automations are paused during the restart and the 2026.8 release notes describe a five-minute confirmation window after which Home Assistant automatically returns to the previous settings and restarts again.[1][2]
- Safer check
- Confirm that the reverse proxy upstream points to the Home Assistant host and port, that the proxy itself is healthy, and that you can reach Home Assistant directly on its local port as a fallback. Note the current Trust X-Forwarded-For and Trusted proxies values before changing them.[1]
- Expected result
- After Home Assistant restarts, the same request through the reverse proxy succeeds and direct access still works. If the new settings cannot be applied or the proxied request still fails, Home Assistant reverts to the previous settings automatically after five minutes.[2]
- Backup / recovery access
- Record the current HTTP server settings and the current configuration.yaml http: block (if any) before saving. Identify the automations and integrations that may pause during the restart and the operator who can confirm the new settings within the five-minute window.[1][2]
- Rollback
- If the proxied request does not succeed or any other change is undesirable, do nothing and Home Assistant automatically reverts to the previous settings after five minutes per the 2026.8 release notes. Otherwise, restore the recorded prior values in the HTTP server section and save again.[2]
Replace a host address with a network address
Edit the Trusted proxies entry so the mask is on the network address (for example, 192.168.1.0/24), not a host address. The HTTP integration documentation requires the network address when a mask is provided. Save the settings; the save restarts Home Assistant.[1]
Before changing anything
- Risk
- Saving the HTTP server settings restarts Home Assistant; automations are paused during the restart.[1]
- Safer check
- Identify the source network the reverse proxy actually uses. Note the current value before editing.[1]
- Expected result
- After the restart, the proxied request succeeds. If the request still fails or any other change is undesirable, Home Assistant reverts to the previous settings after five minutes.[2]
- Backup / recovery access
- Record the current Trusted proxies value and the current configuration.yaml http: block (if any) before saving.[1]
- Rollback
- If the proxied request does not succeed after the restart, do nothing and Home Assistant reverts to the previous settings after five minutes. Otherwise, restore the recorded prior value and save again.[2]
Direct or Cloud access: not a proxy-trust problem
If the deployment is a direct connection without a reverse proxy, the HTTP integration documentation states that Trust X-Forwarded-For and Trusted proxies are not the relevant settings. If the deployment is Home Assistant Cloud, the same documentation states that the settings have no effect on Cloud connections and do not need to be configured for remote access through Cloud.[1]
If the trust boundary cannot be matched: preserve the environment
Record the current Trust X-Forwarded-For and Trusted proxies values, the reverse proxy software and version, the proxy source IP, and the response observed through the proxy. Send the sanitized evidence to the operator before any further change; this page does not authorize disabling authentication or TLS validation as a workaround.[1]
Before any separately scoped restart or automation change
Planning boundary only. The operator must consider the current automations, the five-minute confirmation window described in the 2026.8 release notes, and the recovery access. This page does not disable authentication, disable TLS validation, disable IP banning, or expose the admin interface to a broader network.[1][2]
Before changing anything
- Risk
- Disabling authentication, TLS validation, or IP banning can leave Home Assistant accessible to unauthorized networks and clients.[1]
- Safer check
- First confirm the current Trust X-Forwarded-For and Trusted proxies values and the proxy source network. Do not disable authentication, TLS, or IP banning as a workaround for a proxy trust problem.[1]
- Expected result
- A later owner-approved change must leave the proxy trust boundary narrowly scoped to the actual reverse proxy and must not weaken authentication, TLS, or IP banning. A successful proxied request alone does not validate the broader security configuration.[1]
- Backup / recovery access
- The operator must preserve the current HTTP server settings, identify the automations and integrations affected by the restart, and establish an independent recovery path that does not depend on a restart succeeding before the change.[2]
- Rollback
- No universal restart or automation rollback is supplied. Require an installation-specific restoration plan. If the next start cannot complete or any setting is undesirable, rely on the five-minute automatic revert described in the 2026.8 release notes before further investigation.[2]
Warnings and boundaries
Sources
Links were reviewed on 2026-09-06. Reachability and automated validation do not replace editorial verification of each claim.
- HTTP integration
Home Assistant project · Tier A · accessed 2026-09-06 - 2026.8: Approachable by design
Home Assistant project · Tier A · accessed 2026-09-06