Linux

Caddy 2.11.8 and 2.11.9 Upgrade Guide: Breaking Changes to Check

Caddy 2.11.8 and 2.11.9 tighten PHP, try_files, encode and config validation. Here is what to check before upgrading.

22 November 2026  ·  5 min read  ·  Anand

Caddy 2.11.8 and 2.11.9 Upgrade Guide: Breaking Changes to Check

Caddy shipped two patch releases in early November 2026: 2.11.8 on 4 November and 2.11.9 a day later. We already covered the PHP regression and FastCGI security fixes in 2.11.9. This post is about the other half of the story. Between them, the two releases change a long list of default behaviours, and a few of those changes will break configs that worked last month. If you run Caddy in front of WordPress, Laravel or any other PHP app, or use Caddy as a reverse proxy, read this before you upgrade.

Why these patch releases matter more than usual

Most Caddy patch releases are safe to install without much thought. These two are different. The maintainers fixed a group of path-handling and FastCGI bugs, and many of the fixes work by making Caddy stricter. Requests and config lines that used to be quietly accepted now return an error. The release notes say plainly that some of these fixes may break apps that relied on the old behaviour.

Release binaries are now built with Go 1.27. Go 1.26 is still the minimum if you build Caddy yourself, for example with xcaddy and custom plugins.

Breaking changes to review

PHP and FastCGI

  • Missing paths go to index.php. In php_fastcgi sites, requests for paths that do not exist are now sent to PHP as index.php, which is the documented behaviour. PATH_INFO and DOCUMENT_URI now use the normalized path.
  • Ambiguous script paths get a 400. If the escaped path and the decoded path would point to different scripts, Caddy now rejects the request. On Windows, script paths with 8.3 short names or a : are also rejected.
  • FastCGI env wins over headers. Values you set with env now override any matching HTTP_* header the client sends. If your app read a header that collided with an env value, it will now see your configured value.

try_files and file matching

A try_files or file candidate that ends in / now matches only directories. In 2.11.8 this caused trailing-slash requests such as /wp-admin/ to skip index.php. That regression is fixed in 2.11.9, so skip 2.11.8 and go straight to 2.11.9 if you serve PHP.

Hosts and request bodies

  • Invalid or dots-only host values, such as .., now get a 400 on every protocol. This also closes a way to escape directories in configs like root /srv/sites/{host}.
  • request_body max_size now returns 413 as soon as the Content-Length header is over the limit, rather than after reading the body.

Compression

The encode directive now compresses responses even when the request sends Cache-Control: no-transform. Responses that could be encoded always get Vary: Accept-Encoding. If a client or CDN depended on the old behaviour, you can bring it back with a matcher.

Stricter config validation

Caddy now refuses to load configs that contain:

  • duplicate expression lines
  • unknown TLS curve or protocol names
  • repeated sni_regexp
  • out-of-range ip_mask values
  • duplicate basic_auth usernames
  • overly long port values
  • conflicting client_auth settings in TLS policies that get merged (2.11.9)

The last one is worth noting. Before, Caddy could silently drop the stricter mTLS setting when policies merged. Now it is a Caddyfile error, so you find out at load time instead of running with weaker client authentication than you thought.

Order of evaluation

Multiple handle_errors and vars blocks are now evaluated in the order they appear in the Caddyfile. If you have several of them, check that the order still gives the result you expect.

Useful additions

  • A log_level directive for access logs.
  • A {time.now.rfc3339} placeholder.
  • A not matcher for TLS policies and tls() functions in CEL expressions.
  • Per-route timeouts that override the server-wide read_body_idle and write_idle values.
  • On Linux, Caddy raises CAP_NET_BIND_SERVICE only when it binds a privileged port, so packagers can grant +p instead of +ep.
  • A plain_time_format option for file_server browse (2.11.9).
  • Reverse proxy fixes for retries, load balancing, trailers and several connection leaks.

A safe upgrade checklist

  1. Back up your current config with a clear name, such as Caddyfile.bak-2.11.9-upgrade.
  2. Check your current version with caddy version.
  3. Install 2.11.9 on a staging box or container first, then validate your config with the new binary.
  4. Test the PHP routes that matter: the home page, /wp-admin/, pretty permalinks, file uploads near your size limit and any login pages.
  5. Look for headers your app reads that clash with FastCGI env values.
  6. Upgrade production and reload. Then watch the logs for new 400 and 413 responses.
# Debian/Ubuntu (official Caddy apt repository)
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak-2.11.9-upgrade
sudo apt update && sudo apt install --only-upgrade caddy

# Fedora/RHEL family (Caddy COPR repository)
sudo dnf upgrade caddy

# Validate before reloading
caddy version
caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy
sudo journalctl -u caddy --since '10 min ago'

If caddy validate fails, the error message names the directive that is now rejected. Fix that directive, validate again, and only then reload. Because systemctl reload keeps the old config running when the new one fails to load, a bad config will not take your site down. Still, you should validate first and not rely on that safety net.

Plugin maintainers only need to raise their Caddy dependency if an exported API they use has changed.

How TechProvidence can help

We run Caddy, nginx and Apache in front of PHP and WordPress sites for our clients. We test upgrades in staging, update configs for stricter validation and roll changes out with a tested rollback plan. If you want a hand with your web server upgrades or would like your servers fully managed, contact us.

Source: Caddy releases on GitHub

Running into something similar?

We look after Linux servers, control panels and virtualization for businesses every day. If an update, vulnerability or outage here affects you, we can help.