Nextcloud: The reverse proxy header configuration is incorrect
What each variant of the Nextcloud warning tests, line by line from the setup check, which address goes in trusted_proxies, and why removing it makes things worse.
Key points
- Nextcloud shows this text in two forms. The error ends in "spoof their IP address as visible to the Nextcloud" and means a request arrived with
X-Forwarded-Hostwhiletrusted_proxiesis empty. The warning adds "or you are accessing Nextcloud from a trusted proxy". - The warning means the connection came from an address listed in
trusted_proxies, yet Nextcloud still worked out the proxy's own address as yours. Usually the proxy sent no usableX-Forwarded-For, or your own address is in the trusted list too. - Put the address the proxy connects from, as Nextcloud sees it, into
trusted_proxies. With the proxy in Docker that is its address or subnet on the Docker network, such as172.18.0.0/16, not the server's LAN IP. - Leave
forwarded_for_headersat its default,HTTP_X_FORWARDED_FOR. WritingX-Forwarded-Forthere matches nothing and causes the warning. - Removing
trusted_proxiesis not a fix. Behind Caddy or Traefik it turns the warning into the error. Behind a proxy that sends noX-Forwarded-Hostthe check goes quiet, but users then usually share the proxy's address for logs and brute force throttling.
Nextcloud shows "The reverse proxy header configuration is incorrect" when its setup check finds that it cannot tell your real address apart from your proxy's. The fix is the trusted_proxies list in config/config.php. Set it to the address your reverse proxy connects from, as Nextcloud sees it. Leave forwarded_for_headers at its default. The message comes in two variants, though, and they fail for different reasons.
| Message on the Overview page | What the code found | Fix |
|---|---|---|
| Error: "...This is a security issue and can allow an attacker to spoof their IP address as visible to the Nextcloud." | trusted_proxies is empty and the request carried X-Forwarded-Host | Add the proxy's address to trusted_proxies |
| Warning: "...or you are accessing Nextcloud from a trusted proxy. If not, this is a security issue..." | The peer is listed in trusted_proxies word for word, and the client address still came out as the peer | Make the proxy send X-Forwarded-For, fix forwarded_for_headers, or take your own address out of the list |
| Error: "Your \"trusted_proxies\" setting is not correctly set, it should be an array of IP addresses..." (Nextcloud 29 and later) | An entry is not an IP address or IP/prefix, such as a host name | Use addresses or CIDR ranges only |
Every row comes from ForwardedForHeaders.php in the Nextcloud server source. The sections below walk through it.
What the terms mean here#
A reverse proxy is the server that faces the internet and passes requests on to Nextcloud. Nginx, Caddy, Traefik, HAProxy and Nginx Proxy Manager are common ones. The proxy usually handles HTTPS. It then talks to Nextcloud over plain HTTP.
Nextcloud sees the TCP connection from the proxy, not from the visitor. The address at the other end of that connection is the peer. PHP stores it in REMOTE_ADDR. Behind a proxy, the peer is the proxy.
So the proxy passes the visitor's address along in a header, almost always X-Forwarded-For. That header is a comma-separated list. 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 Nextcloud must decide whose header to believe. trusted_proxies is the list of peers whose forwarding headers Nextcloud believes. The config sample allows single IPv4 or IPv6 addresses and CIDR ranges. forwarded_for_headers names the headers that carry the client address. Its default is HTTP_X_FORWARDED_FOR, which is PHP's name for X-Forwarded-For.
The setup check is the test that fills the warnings box under Administration settings > Overview. This one is called "Forwarded for headers". It reads the request that asked for the check. When you open the Overview page, that request is your own browser's. So the result describes the path your browser took, and nobody else's.
What the check does, step by step#
The code is short. This is the current master branch. The error and warning conditions are the same in every release from 28.0.0 to 32.0.0. It runs in this order:
- Is
trusted_proxiesan array? If not, it returns an error saying so. - Is every entry an address? Each entry is split at
/. The left part must be a valid IP and the right part, if any, must be digits. Otherwise you get the "array of IP addresses" error. This check arrived in Nextcloud 29. - No peer address at all? From
occ setupcheckson the command line, it returns info: "Your remote address could not be determined." So the command line never shows this warning. - List empty, and
X-Forwarded-Hostpresent? It returns the error variant. - Peer listed word for word, and not
127.0.0.1? It asks Nextcloud for the client address. If that differs from the peer, the check passes with "Your IP address was resolved as" and the address. If it equals the peer, you get the warning variant. - Anything else passes with no message. The code comment reads: "Either not enabled or working correctly."
The client address in step 5 comes from getRemoteAddress() in Request.php. If the peer is in trusted_proxies, it reads each header in forwarded_for_headers. It walks each list from the right. It skips every entry that is itself a trusted proxy. The first valid address that is not trusted becomes the client. If none is found, it keeps the peer. That is the same right-to-left walk that configuring trusted proxies describes for other servers. The client IP resolver runs it on a header and trusted list you paste in, so you can see which address Nextcloud would pick.
The error: X-Forwarded-Host with an empty list#
The error fires on one header only: X-Forwarded-Host. Many forum answers say X-Forwarded-For sets it off too. The code does not test X-Forwarded-For here. A proxy that sends only X-Forwarded-For, with an empty list, gets no message from this check.
Whether your proxy sends X-Forwarded-Host depends on the proxy:
- Caddy sets it by default. Its
reverse_proxydocs list three headers it always sets:X-Forwarded-For,X-Forwarded-ProtoandX-Forwarded-Host. - Traefik sets it too. Its forwarded-headers code copies the request's
HostintoX-Forwarded-Hostwhen the header is empty. - Nginx Proxy Manager does not. Its
proxy.confsendsX-Forwarded-Scheme,X-Forwarded-Proto,X-Forwarded-ForandX-Real-IP, and noX-Forwarded-Host. - Plain nginx sends only the headers you write with
proxy_set_header.
So the error is mostly a Caddy and Traefik message. The fix is to fill in trusted_proxies. Any valid, non-empty list clears this branch. Only the right address makes the rest work.
Up to Nextcloud 27, the two conditions shared one message: the warning text. The separate error text arrived in 28.0.0. That is why older forum threads quote only the warning.
The warning: a trusted peer, but no client address#
The warning needs two things at once. The peer's address must appear in trusted_proxies as an exact string. And the client address that Nextcloud works out must still equal that peer. In other words, Nextcloud trusted the proxy, looked for the visitor's address, and came back with nothing better.
That happens in four ways:
- The proxy sends no
X-Forwarded-For. There is nothing to read, so the peer stays. forwarded_for_headersuses the wrong names. The values are PHP lookup keys. The docs say "'X-Forwarded-For' becomes 'HTTP_X_FORWARDED_FOR'". WriteX-Forwarded-Forand the lookup finds nothing, so the peer stays.- Every entry in the header is trusted. The walk skips trusted entries. Suppose you added your home LAN,
192.168.1.0/24, totrusted_proxiesand browse from192.168.1.50. Your own address is skipped as a "proxy". Nothing is left, so the peer stays. This is what "you are accessing Nextcloud from a trusted proxy" means. - No entry is a valid IP. A value like
unknownfails PHP's IP check. A port is fine: the code strips:portfrom IPv4 and[...]:portfrom IPv6.
The first two are real faults. The third is the case the message itself allows for. It is still worth fixing, because trusting a whole LAN lets any device on it set its own address. Client IP spoofing through proxies shows what that breaks.
A clean check does not prove the setup works#
Step 5 compares the peer with the list using PHP's in_array() in strict mode. That is a plain string match. It does not understand CIDR. The real client lookup in Request.php does understand CIDR, through IpUtils::checkIp().
So the check and the lookup can disagree:
- A CIDR entry never triggers the warning. With
trusted_proxiesset to['172.18.0.0/16'], a peer at172.18.0.2is trusted by the lookup. The check's string match fails, so it falls through to step 6 and passes, with no message. If the lookup is broken, you are not told. 127.0.0.1is exempt. A proxy on the same machine, connecting over127.0.0.1, never gets the warning.::1is not exempt.- A peer outside the list also passes. If you trusted the wrong address, the check is silent, and Nextcloud simply records the proxy as every visitor.
The only positive proof the check gives is the line "Your IP address was resolved as" followed by your public address. It appears only when the peer is listed as a single address. With a CIDR list, check the client address another way. The brute force docs give the method: look in the Nextcloud log "to see what IP addresses are being detected". If every client shows the proxy's address, they say, "you need to review your trusted_proxies configuration".
Which address goes in trusted_proxies#
Put in the peer: the address the proxy connects from, as Nextcloud sees it. That is often not the address people expect.
- 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
127.0.0.1or::1. - Proxy and Nextcloud in Docker, on a shared network. The peer is the proxy container's address on that Docker network, often a
172.xaddress. It is not the Docker host's LAN IP.docker network inspect <network>shows the subnet and each container's address. - A CDN or tunnel in front of your proxy. Your own proxy is still the peer. The CDN's addresses only matter to the proxy that receives from it.
Unless you give a container a fixed address, Docker picks one when it starts. So for a proxy in Docker, trusting the network's subnet is sturdier than trusting one address. It also trusts every other container on that network. Keep the proxy on a network with nothing else you do not control.
In config/config.php, the setting looks like this:
'trusted_proxies' => ['172.18.0.0/16'],The official Docker image builds the same setting from the TRUSTED_PROXIES variable, split on spaces: TRUSTED_PROXIES=172.18.0.0/16. It does the same for FORWARDED_FOR_HEADERS and each OVERWRITE* value.
The official Apache image rewrites the peer first#
The official image's Apache variant turns on mod_remoteip by default. Its Dockerfile sets RemoteIPHeader X-Real-IP and trusts 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 as internal proxies. The README says this replaces "the remote addr (IP address visible to Nextcloud) with the IP address from X-Real-IP" for proxies in those ranges.
That changes what Nextcloud sees. Nginx Proxy Manager sends X-Real-IP, and Traefik's code sets X-Real-Ip to the client's address. So behind either one in a 172.x network, Apache has already put the visitor's address into REMOTE_ADDR before Nextcloud runs. The peer is no longer the proxy, so the check passes whatever trusted_proxies holds.
Caddy does not set X-Real-IP. Its docs say it passes incoming headers through unchanged, apart from its three X-Forwarded-* headers. So a normal request reaches Apache with no X-Real-IP, and the peer stays Caddy. But a visitor who adds their own X-Real-IP header gets it passed through, and Apache believes it, because Caddy's address is in a trusted range.
The README gives the switch for the other route. Set APACHE_DISABLE_REWRITE_IP=1 and list the proxy in TRUSTED_PROXIES. Nextcloud then reads X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host itself. Behind Caddy, this is the route to take. Leaving the rewrite on means Apache believes X-Real-IP from any device in the three private ranges, not only from your proxy.
forwarded_for_headers: leave the default#
The default is one header, HTTP_X_FORWARDED_FOR. A comment in Request.php says why there is only one: "so we cannot ship an insecure product out of the box". The config sample warns that a wrong value "allows clients to spoof their IP address, bypassing access controls and rendering logs unreliable".
Change it only if your proxy puts the client address somewhere else. Then use the PHP form: X-Real-IP becomes HTTP_X_REAL_IP. List only headers your proxy always sets and overwrites. A header the proxy passes through untouched is one the visitor writes.
The overwrite settings fix URLs, not this warning#
The check never reads overwriteprotocol, overwritehost, overwrite.cli.url or overwritecondaddr. Setting them will not clear this message. They fix the URLs Nextcloud builds, which is a separate problem with its own setup checks.
overwriteprotocolforceshttporhttps. Without it, Nextcloud takesX-Forwarded-Proto, but only from a trusted peer. Behind a TLS proxy with no trusted list, it thinks it runs onhttp.overwritehostforces the host name. Without it, Nextcloud takesX-Forwarded-Hostfrom a trusted peer, or elseHost. The docs say it "is not needed in most setups".overwrite.cli.urlis the base URL for links made by command-line jobs, where there is no request to read.overwritecondaddris a regular expression for the peer address. When set,overwritehostandoverwriteprotocolapply only to requests from matching peers. The docs' example is'^10\.0\.0\.1$'.
The docs' subdirectory example puts them together for a proxy at 10.0.0.1:
'trusted_proxies' => ['10.0.0.1'],
'overwriteprotocol' => 'https',
'overwritewebroot' => '/nextcloud',
'overwrite.cli.url' => 'https://example.com/nextcloud',X-Real-IP, X-Forwarded-Proto, Host and Port covers the headers these settings stand in for.
"Just remove trusted_proxies" makes it worse#
A common forum answer says the list is not needed if the proxy is set up right, so remove it. Follow the code and it never helps.
- Behind Caddy or Traefik the warning becomes the error. Both send
X-Forwarded-Host, and step 4 fires as soon as the list is empty. - Behind a TLS proxy without
overwriteprotocol, Nextcloud stops readingX-Forwarded-Proto. It decides the site is plainhttp. The HTTPS check then reports "Accessing site insecurely via HTTP" as an error. - Behind Nginx Proxy Manager or plain nginx, which send no
X-Forwarded-Host, the check goes quiet. That looks like a fix. In fact Nextcloud now records the proxy's address for every visitor. The one exception is the official Apache image behind NPM, where Apache'sX-Real-IPrewrite still supplies the address.
The last one has a cost you can name. Nextcloud's brute force protection works by IP address. Its docs warn that with trusted_proxies wrong, "Nextcloud actually starts throttling all traffic coming from the reverse proxy". One person mistyping a password slows logins for everyone. The warning was about a real fault, and removing the list hides it.
Worked case: Caddy and the official image in Docker#
Take a common setup. Caddy and the nextcloud Apache image run as two containers on one Docker network. Say the network is 172.18.0.0/16 and Caddy has 172.18.0.2. Caddy ends HTTPS for cloud.example.com and proxies to Nextcloud on port 80. The admin's phone is at 203.0.113.50. Walk one Overview page load through each setting.
No trusted_proxies. Caddy sends X-Forwarded-For: 203.0.113.50, X-Forwarded-Proto: https and X-Forwarded-Host: cloud.example.com. It sends no X-Real-IP, so Apache leaves REMOTE_ADDR at 172.18.0.2. The list is empty and X-Forwarded-Host is present. That is step 4: the error.
trusted_proxies set to ['192.168.1.10'], the server's LAN IP. This is the most common guess. The list is no longer empty, so the error goes. But the peer 172.18.0.2 is not listed, so step 6 passes the check silently. Nextcloud ignores the headers and records 172.18.0.2 for every visitor. The page is green and the setup is wrong.
trusted_proxies set to ['172.18.0.2']. The peer matches as a string. The lookup reads X-Forwarded-For, finds 203.0.113.50, and that is not trusted. So the client is 203.0.113.50, which differs from the peer. The check passes with "Your IP address was resolved as 203.0.113.50". This is the setting that proves itself.
Same list, plus forwarded_for_headers set to ['X-Forwarded-For']. There is no server key named X-Forwarded-For, so the lookup reads nothing and keeps the peer. The client equals the peer: the warning.
trusted_proxies set to ['172.18.0.2', '192.168.1.0/24'], and the admin is on the LAN at 192.168.1.50. Caddy sends X-Forwarded-For: 192.168.1.50. That entry is inside a trusted range, so the walk skips it. Nothing is left, so the client is the peer: the warning, on the LAN only. From the phone it passes.
trusted_proxies set to ['172.18.0.0/16']. The lookup works and finds 203.0.113.50. But the string match fails, so the check passes with no message. The setup is right. You confirm it in the log, not on the Overview page.
One more line belongs in this setup: APACHE_DISABLE_REWRITE_IP=1. None of the walk above changes, because Caddy's own requests carry no X-Real-IP. It closes the gap where a visitor sends that header through Caddy and Apache believes it.
Where this answer stops applying#
Every rule here comes from reading the Nextcloud server source on master, with the check's conditions compared against tags 27.1.0, 28.0.0, 29.0.0 and 30.0.0 to 32.0.0. Nothing was run against a live Nextcloud, and the worked case is a walkthrough. The Docker addresses are examples; your peer is whatever docker network inspect shows. The Apache image details come from the current nextcloud/docker repository; its fpm Dockerfile has no remoteip setup. Proxy headers come from Caddy's docs, Traefik's source and Nginx Proxy Manager's develop branch; check yours if it differs. This page covers only the "Forwarded for headers" check. It does not cover trusted_domains, the CalDAV and CardDAV .well-known redirects, or HSTS. For a sibling case that refuses requests instead of warning, see Home Assistant 400 Bad Request behind a reverse proxy.
Frequently asked questions#
What does "The reverse proxy header configuration is incorrect" mean in Nextcloud?#
Nextcloud's setup check could not confirm that it sees your real address rather than your proxy's. The error variant means X-Forwarded-Host arrived while trusted_proxies was empty. The warning variant means the proxy was trusted, but your address still came out as the proxy's.
Should I remove trusted_proxies to get rid of the warning?#
No. Behind Caddy or Traefik, removing it turns the warning into the error. Behind other proxies, it usually hides the message while Nextcloud records the proxy's address for every user, which the brute force docs say can throttle all traffic from the proxy.
What IP should trusted_proxies be when Nextcloud runs in Docker?#
The address the proxy container connects from, on the Docker network the two share, or that network's subnet, such as 172.18.0.0/16. It is not the host's LAN IP. docker network inspect shows both values.
Why do I still see the warning after adding my proxy's IP?#
Most often forwarded_for_headers is set to X-Forwarded-For instead of HTTP_X_FORWARDED_FOR, the proxy sends no X-Forwarded-For, or your own address is inside a trusted range. In each case Nextcloud ends up with the proxy's address as yours.
Why does the warning appear only on my LAN?#
Your LAN range is probably in trusted_proxies. Nextcloud skips trusted addresses when it reads X-Forwarded-For, so your own address is skipped and the proxy's is kept. List only the proxy, not the whole LAN.
Does overwriteprotocol or overwritehost fix this warning?#
No. The check reads only trusted_proxies, the peer address, X-Forwarded-Host and the client lookup. The overwrite settings fix the URLs Nextcloud generates, which is a separate check.
Does a CIDR range in trusted_proxies work?#
Yes, for the client lookup, which uses IpUtils::checkIp(). The setup check uses an exact string match, so with a CIDR entry it never shows the warning or the "resolved as" line. Confirm the result in the log instead.
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.
- Nextcloud server, apps/settings/lib/SetupChecks/ForwardedForHeaders.php (master; same conditions in v28.0.0 to v32.0.0)
- Nextcloud server, lib/private/AppFramework/Http/Request.php (getRemoteAddress, getServerProtocol, overwrite handling)
- Nextcloud server v27.1.0, CheckSetupController.php (forwardedForHeadersWorking, before the split into two messages)
- Nextcloud server, apps/settings/lib/SetupChecks/HttpsUrlGeneration.php
- Nextcloud server, config/config.sample.php (trusted_proxies, forwarded_for_headers, overwrite parameters)
- Nextcloud Administration Manual, Reverse proxy
- Nextcloud Administration Manual, Brute force protection
- Nextcloud Docker image, README (reverse proxy section) and .config/reverse-proxy.config.php
- Nextcloud Docker image, 35/apache/Dockerfile (remoteip configuration)
- Caddy documentation, reverse_proxy directive (default headers)
- Traefik source, pkg/middlewares/forwardedheaders/forwarded_header.go
- Nginx Proxy Manager source, docker/rootfs/etc/nginx/conf.d/include/proxy.conf
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.