A Caddy reverse proxy makes it easy to route incoming web requests to applications running on different ports or servers. When it stops working, however, the cause may not be obvious at first. DNS problems, incorrect Caddyfile directives, unavailable upstream services, firewall rules, or TLS configuration can all prevent requests from reaching the application.
This guide explains how to troubleshoot a Caddy reverse proxy not working situation step by step.
1. Check the Caddy Configuration
Start by verifying that Caddy can parse your configuration. A syntax error or unsupported directive can prevent Caddy from loading the configuration correctly.
For a Caddyfile, validate the configuration with:
caddy validate –config /etc/caddy/Caddyfile
You can also format the file to make configuration problems easier to identify:
caddy fmt –overwrite /etc/caddy/Caddyfile
A basic reverse proxy configuration may look like:
example.com {
reverse_proxy local host:8080
}
Make sure the domain name, upstream address, and port match your actual setup.
2. Verify That Caddy Is Running
A valid configuration does not help if the Caddy service itself is stopped or failing.
Check its status:
systemctl status caddy
If necessary, restart it:
systemctl restart caddy
Then check recent service messages:
journalctl -u caddy –no-pager -n 100
Look for messages related to configuration loading, listener failures, certificate problems, or connection errors.
3. Test the Upstream Application
One of the most common causes of reverse proxy failures is an unavailable back end application.
Suppose Caddy is configured with:
reverse_proxy local host:8080
Test the application directly:
curl http://local host:8080
If this request fails, the problem may be with the application rather than Caddy.
Verify that a service is listening on the expected port:
ss -lntp | grep 8080
If nothing is listening, start or troubleshoot the back end service before changing the Caddy configuration.
4. Check the Upstream Address
The address used by reverse_proxy must be reachable from the server running Caddy.
For example:
reverse_proxy 127.0.0.1:8080
is different from:
reverse_proxy 192.168.1.20:8080
The second configuration requires network connectivity to another machine.
You can test remote connectivity with:
curl http://192.168.1.20:8080
If the back end is inside a container, remember that local host usually refers to the container itself, not the host or another container. In Docker-based deployments, the correct service name or network address may need to be used.
5. Verify DNS Resolution
If users cannot reach the domain, check DNS before changing the proxy configuration.
Run:
dig +short example.com
The result should point to the server where Caddy is running.
Also verify that both IPv4 and IPv6 records are intentional. An incorrect AAAA record can cause some clients to connect to the wrong server even when the A record is correct.
6. Check Ports and Firewall Rules
Caddy normally needs to accept incoming HTTP and HTTPS traffic.
Check listening ports:
ss -lntp | grep -E ‘:80|:443’
If Caddy is listening correctly but external connections fail, inspect the server firewall, cloud firewall, security group, or network ACL.
For example, ensure TCP ports 80 and 443 are permitted where required.
Also check whether another service is already using those ports. A port conflict can prevent Caddy from starting or binding to the expected address.
7. Troubleshoot HTTPS and TLS
Caddy automatically manages HTTPS certificates in many standard configurations, but certificate issuance can still fail.
Check the Caddy logs:
journalctl -u caddy -f
Common causes include incorrect DNS records, blocked port 80, rate limits, or domain validation problems.
If HTTPS works but the application returns an error, test the connection directly:
curl -v https://example.com
This can reveal certificate, redirect, connection, and HTTP response problems.
8. Examine Caddy Logs
Logs are often the fastest way to see why a reverse proxy request fails.
Depending on the configuration, enable structured access logging:
example.com {
log
reverse_proxy local host:8080
}
Then inspect the generated logs and look for HTTP status codes such as 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout.
A 502 commonly indicates that Caddy could not successfully communicate with the upstream application. A timeout can indicate that the upstream is unreachable, overloaded, or taking too long to respond.
9. Test the Request Path by Path
Instead of testing everything simultaneously, isolate each component:
Client → DNS → Caddy → Upstream Application
First confirm DNS points to the correct server. Then verify that Caddy is listening on ports 80/443. Next, test the back end directly with curl. Finally, test the complete public URL.
This approach helps identify exactly where the request is failing.
Conclusion
When a Caddy reverse proxy is not working, avoid immediately rewriting the entire configuration. Start with the basics: validate the Caddyfile, confirm that Caddy is running, test the upstream application, verify DNS, check ports and firewall rules, and inspect the logs.
Breaking the request path into individual components makes troubleshooting much faster. Once you identify whether the failure is between the client and Caddy or between Caddy and the upstream application, the appropriate fix becomes much easier to determine.
Facing issues?
Our technical support
engineers can solve it.
