Guide
Nextcloud "Your web server is not properly set up to resolve /.well-known/caldav"
The warning stays because Nextcloud tests the URL from the server, without logging in, and a rewrite looks like a failure to that test. We ran the check on Nextcloud 35 in Docker behind Caddy, Traefik, Nginx Proxy Manager and a Cloudflare quick tunnel, and logged every request it made.
Why does Nextcloud say it is not properly set up to resolve /.well-known/caldav when the redirect works in a browser?
Since Nextcloud 29 the check runs on the server, not in your browser. It sends a PROPFIND to /.well-known/caldav without logging in. It passes on 207, or on 401 only if a redirect led there and the last URL ends in /remote.php/dav. A proxy rule that rewrites the path gives a 401 with no redirect, so it fails, even though logged-in clients work. Make the proxy redirect instead: redir in Caddy, redirectRegex in Traefik, return 301 in Nginx Proxy Manager's Advanced tab.
The warning stays because your browser is not what runs the test. Since Nextcloud 29, the Nextcloud server sends the request itself, with no login. It sends PROPFIND /.well-known/caldav and accepts only two answers: 207, or 401 reached through a redirect whose last URL ends in /remote.php/dav. A proxy rule that rewrites the path answers 401 with no redirect, so the check fails. Your browser and your logged-in clients still work. Make the proxy redirect instead of rewrite:
cloud.example.com {
redir /.well-known/carddav /remote.php/dav/ 301
redir /.well-known/caldav /remote.php/dav/ 301
reverse_proxy nextcloud:80
}That is the Caddy block from the admin manual. The Traefik and Nginx Proxy Manager versions are further down. On Nextcloud 35 the message now reads "Your web server is not properly set up to resolve .well-known URLs, failed on: /.well-known/caldav". Older versions said "not properly set up to resolve "/.well-known/caldav"". It is the same check.
The terms this answer turns on#
/.well-known/caldav and /.well-known/carddav are fixed addresses that calendar and contacts apps ask first. The server is meant to point them at its real CalDAV and CardDAV endpoint. On Nextcloud that endpoint is /remote.php/dav/. The admin manual calls this service discovery. It is what lets a phone or a Mac find your calendars from the server name alone.
PROPFIND is a WebDAV request. It asks for facts about a resource. A 207 answer, "Multi-Status", means the server returned them. A 401 means "log in first".
A redirect sends the client a new address, and the client asks again there. A rewrite changes the path inside the proxy and passes the request on. The client never learns about it. To a client the two look different, and this check can tell them apart.
The setup check is the list of warnings on Administration settings, Overview. Each one is a small test. This one is WellKnownUrls.php.
Why a working browser redirect proves nothing#
Opening https://cloud.example.com/.well-known/caldav in a browser tests a GET, sent from your network, by a logged-in user. The check differs in all three ways.
It sends PROPFIND, not GET. It sends it from inside the Nextcloud server, or the container in Docker. And it sends no login. So it can never get the 207 a logged-in client gets. It has to settle for a 401, and the code accepts a 401 only when the redirect history ends in /remote.php/dav.
That rule is why the threads disagree. In the 2021 Traefik thread, a user had a working redirectRegex and still saw the warning. Replies offered replacePathRegex, and in 2023 one user said it "works fine". It did, then. Nextcloud 28's setupchecks.js sent the PROPFIND from the browser, with the admin's session, so a rewrite got 207. Nextcloud 29 moved the check into PHP. The same rewrite now fails.
What the check does, step by step#
From WellKnownUrls.php and CheckServerResponseTrait.php:
- Four URLs, in order. GET
/.well-known/webfinger(pass on 200, 400 or 404), GET/.well-known/nodeinfo(200 or 404), then PROPFIND/.well-known/caldavand/.well-known/carddav. Webfinger and nodeinfo also need theX-NEXTCLOUD-WELL-KNOWNheader, which only Nextcloud adds. - A list of base addresses for each URL. First
overwrite.cli.url. Then the address Nextcloud builds from the current request, which is the one in your browser bar. Then each entry intrusted_domains, withhttps://and thenhttp://. Wildcard entries are skipped. Duplicates are dropped. - Stop at the first pass. If any address passes, that URL is fine.
- Connection errors are skipped. TLS certificates are not verified, and each connection gets 10 seconds. If nothing connects, the result is the info message "Could not check". If something answered and nothing passed, it is the warning, naming the URL that failed.
- Redirects are followed. Nextcloud's HTTP client is Guzzle. Its code turns a PROPFIND into a GET after a 301 or 302, and keeps PROPFIND after a 307 or 308. Both pass, because the 401 at the end counts.
Setting check_for_working_wellknown_setup to false skips all of it.
Which address does it test in Docker?#
The official image's automated install leaves localhost at index 0 of trusted_domains. It also sets overwrite.cli.url to http://localhost, or https://localhost if OVERWRITEPROTOCOL=https was set. Our install had the second.
We ran nextcloud:apache (Nextcloud 35.0.2, Apache 2.4.69, SQLite) with a public name of cloud.example.test. We loaded the setup check through the proxy, as an admin's browser would, and read Apache's access log to see where each request came from.
https://localhost refused the connection, because nothing listens on 443 inside the container. So the next address, the public name, went through the proxy. When that failed, http://localhost reached the container's own Apache and passed. Apache's .htaccess has its own rule, RewriteRule ^\.well-known/caldav /remote.php/dav/ [R=301,L].
Proxy set-up, localhost still trusted | Result | Requests that passed came from |
|---|---|---|
Caddy 2.11.7, plain reverse_proxy | Pass | Caddy |
Caddy with rewrite to /remote.php/dav/ | Pass | 127.0.0.1, the container itself |
Caddy answering 404 to all of /.well-known/* | Pass | 127.0.0.1 |
So on the official Apache image, as installed, the warning is close to impossible. The check is not testing your proxy. If you see the warning there, localhost is missing from trusted_domains, for example because Nextcloud was installed through the browser. Then every request goes through the public name.
What each proxy does when only the public name is tested#
Next we removed localhost and set overwrite.cli.url to https://cloud.example.test, the setting our untrusted domain guide recommends. Now only the proxy path counts.
| Proxy and rule | What the PROPFIND got | Check |
|---|---|---|
| Caddy, no rule, Caddy's own HTTP to HTTPS redirect | 301 from Apache to http://, then 308 to https://, then 401 | Pass |
| Caddy, no rule, no plain HTTP listener | 301 to http://, which nothing answered | Info, "Could not check" |
Caddy redir ... 301 | 301, then 401 | Pass |
Caddy rewrite | 401, no redirect | Warning, caldav |
Caddy respond /.well-known/* 404 | 404 without the Nextcloud header | Warning, webfinger |
| Traefik 3.7.17, no rule, port 80 redirects to 443 | Same as Caddy, no rule | Pass |
Traefik redirectRegex, the admin manual's regex, permanent: true | 308, then 401 | Pass |
Traefik redirectRegex, path-only regex from the 2021 thread | 308, then 401 | Pass |
Traefik redirectRegex without permanent | 307, then 401 | Pass |
Traefik replacePathRegex | 401, no redirect | Warning, caldav |
| Nginx Proxy Manager 2.16.0, default proxy host | Same as Caddy, no rule | Pass |
NPM custom location /.well-known/caldav to nc/remote.php/dav/ | 401, no redirect | Warning, caldav |
NPM Advanced tab, return 301 | 301, then 401 | Pass |
| Cloudflare quick tunnel (cloudflared 2026.10.7), no rule | 301 to http://, Cloudflare's 301 to https://, then 401 | Pass |
Two things stand out. First, "no rule" often passes. Apache's own 301 points at http://, because Apache sees plain HTTP from the proxy. The admin manual says these redirects "does not work if Nextcloud is running behind a reverse proxy" and asks the proxy to do them. Still, a proxy that sends HTTP on to HTTPS rescues the http:// address. Second, every rewrite failed. A logged-in PROPFIND through the Traefik rewrite still got 207, so clients that log in were fine. Only the check objected.
The fix for each proxy#
Caddy. Use redir, as in the block at the top. Caddy's docs say permanent and the default temporary let the client change the method. That is fine here: the check accepts the GET that follows.
Traefik. Use redirectRegex, never replacePathRegex, for these two paths. The admin manual's labels work as written:
- "traefik.http.routers.nextcloud.middlewares=nextcloud_redirectregex@docker"
- "traefik.http.middlewares.nextcloud_redirectregex.redirectregex.permanent=true"
- "traefik.http.middlewares.nextcloud_redirectregex.redirectregex.regex=https://(.*)/.well-known/(?:card|cal)dav"
- "traefik.http.middlewares.nextcloud_redirectregex.redirectregex.replacement=https://$${1}/remote.php/dav"The regex is matched against the full URL, scheme included. Traefik answered our PROPFIND with 308 when permanent was true and 307 when it was not.
Nginx Proxy Manager. A custom location that forwards to /remote.php/dav/ is a rewrite, and it failed. Put redirects in the proxy host's Advanced tab instead:
location = /.well-known/carddav { return 301 $scheme://$host/remote.php/dav/; }
location = /.well-known/caldav { return 301 $scheme://$host/remote.php/dav/; }Cloudflare Tunnel. cloudflared cannot redirect, and with no rule our quick tunnel passed through Apache's own 301. If you need a rule on your own zone, it has to be a redirect at Cloudflare's edge. We did not test that.
nginx in front of the FPM image. The admin manual's block uses return 301 for both paths, plus return 301 $scheme://$host/index.php$uri for the rest of /.well-known.
A worked case: Traefik with replacePathRegex#
Take a common set-up: Nextcloud behind Traefik, with the replacePathRegex middleware copied from a forum reply. Suppose it was installed through the browser at the public name, so trusted_domains holds only cloud.example.com.
Walk the check through it. overwrite.cli.url is the public name, so the first request goes to Traefik. Webfinger and nodeinfo reach Nextcloud and come back 404 with the Nextcloud header, so they pass. Then PROPFIND /.well-known/caldav arrives. Traefik changes the path to /remote.php/dav/ and passes it on. Nextcloud answers 401, since there is no login. There was no redirect, so the history is empty, and the check marks it failed. The next address, http://cloud.example.com, gets Traefik's redirect to HTTPS and then the same rewrite. The 401 arrives after a redirect, but the last URL is /.well-known/caldav, not /remote.php/dav. That fails too. No address is left, so the warning names caldav.
Swap the middleware for the redirectRegex above. The PROPFIND now gets a 308 to /remote.php/dav, then a 401 there. The history ends in /remote.php/dav, and the check passes at the first address.
When the public name does not work from inside the container#
Many routers cannot send a connection from inside the LAN back in to their own public address. This is called hairpin NAT, or NAT loopback. Then the check cannot reach your proxy at all.
We pointed the public name at an address the container could not reach. Every request timed out, and the result was the info message, not the warning. The setup check page took 182 seconds to load, because seven other setup checks also send requests to the server this way. The fix is to make the name resolve to the proxy from inside: split DNS, as in DNS for self-hosters, or an extra_hosts entry in compose.
What this does not cover#
We measured the Apache variant of the official image only. On the FPM image, localhost inside the app container has no web server, so the fallback we saw cannot happen and only the proxy path counts. We read that from the code and did not run it. We did not test Nextcloud AIO, the LinuxServer image, HAProxy, or redirect rules on a real Cloudflare zone. Passing the check also proves less than it seems. It accepts a 401 at /remote.php/dav from any redirect, and it never logs in. Whether a given phone or calendar app finds your calendars is a separate test, and the only proof is adding the account with the server name alone. Clearing this warning does not fix the others on the same page, such as the http:// links covered in the untrusted domain guide.
What to do next#
Read the URL the warning names. For caldav or carddav, change your rewrite to a redirect and reload the overview page, since the check runs fresh each time. For webfinger or nodeinfo, let those paths reach Nextcloud. If http:// links appear anywhere, set trusted_proxies and overwriteprotocol as in Nextcloud "Access through untrusted domain" behind a reverse proxy. Reverse proxy and TLS covers the rest of the proxy set-up. If the tunnel itself returns errors, Why Cloudflare Tunnel returns 502 Bad Gateway with cloudflared in Docker reads them. The Nextcloud profile lists the other traps that come with running it.
Questions#
Why did replacepathregex work for Traefik users in old forum threads?
Because up to Nextcloud 28 the check ran in your browser. The script in setupchecks.js sent the PROPFIND with your login, so a rewrite got 207 and passed. From Nextcloud 29 the server sends it with no login. A rewrite now gets 401 with no redirect, and the check fails. In our lab, replacePathRegex gave the warning on Nextcloud 35, while a logged-in PROPFIND through it still got 207.
Is the .well-known warning safe to ignore?
Sometimes. If your rule rewrites the path and your calendar and contacts apps sync, the warning comes from the check's rule, not from a broken path. Our logged-in PROPFIND through a rewrite got 207. If no rule exists and the warning names caldav or carddav, check a phone or a Mac with only the server name before you ignore it. The admin manual lists these URLs under service discovery, which is how those clients find the DAV endpoint.
How do I turn off the .well-known check in Nextcloud?
Set check_for_working_wellknown_setup to false: docker compose exec -u www-data app php occ config:system:set check_for_working_wellknown_setup --value=false --type=boolean. The code then skips the test and shows an info line saying it was skipped. Do this only after you have checked service discovery by hand, because nothing will tell you if the redirect breaks later.
What does "Could not check that your web server serves .well-known correctly" mean?
Every request the check tried failed to connect, so it has no answer either way. It is shown as info, not as a warning. In our lab this happened when the public name pointed at an address the container could not reach, and when the proxy had no plain HTTP listener for the http:// redirect Nextcloud's Apache sends. Point the name at the proxy from inside the container, or set overwrite.cli.url to an address that answers.
Why does the warning say webfinger instead of caldav?
The check tests four URLs in order: webfinger, nodeinfo, caldav, carddav. It stops at the first one that fails and names it. Webfinger and nodeinfo pass on 404, but only if the answer carries the X-NEXTCLOUD-WELL-KNOWN header, which means Nextcloud itself answered. A proxy that answers /.well-known/ paths on its own fails there. Ours did, with a plain 404.
Sources#
- Nextcloud server, WellKnownUrls.php (the setup check, same in stable35 and master)
- Nextcloud server, CheckServerResponseTrait.php (which URLs the server requests)
- Nextcloud server 28, core/js/setupchecks.js (the old browser-side check)
- Nextcloud server, .htaccess (the Apache well-known redirects)
- Nextcloud admin manual, reverse proxy: service discovery
- Guzzle, RedirectMiddleware.php (301 and 302 turn PROPFIND into GET)
- Caddy documentation, redir directive
- Nextcloud forum, ".well-known seems to work but still a warning (using Traefik)" (2021 to 2024)
- Nextcloud forum, "Your web server is not properly set up to resolve /.well-known/caldav" (2019)
Published . Last reviewed . Found something out of date? Tell us and we will fix it and log the change.