====== Troubleshooting =====

Resolve common issues with Caddy and Docker setup.

> //Most Caddy issues relate to certificates, networking, or backend service problems.//

===== Overview =====

Common issues with Caddy include certificate issuance failures, 502 Bad Gateway errors, and configuration problems. This guide helps you diagnose and resolve these issues.

===== Certificate Issuance Failed =====

**Symptoms:**
  * HTTPS not working
  * Certificate errors in browser
  * Caddy logs show certificate errors

**Troubleshooting:**
  * Check DNS propagation: `nslookup your-domain.com`
  * Verify ports 80 and 443 are accessible externally
  * Check Caddy logs: `docker compose logs caddy`
  * Ensure domain points to correct IP
  * Wait for DNS propagation (can take up to 48 hours)

===== 502 Bad Gateway =====

**Symptoms:**
  * Browser shows 502 error
  * Service appears down

**Troubleshooting:**
  * Check if backend container is running: `docker compose ps`
  * Check backend container logs: `docker compose logs service-name`
  * Verify service name in Caddyfile matches docker-compose.yml
  * Check network connectivity between containers
  * Ensure backend service is listening on correct port

===== Container Won't Start =====

**Symptoms:**
  * Container exits immediately
  * Container won't start

**Troubleshooting:**
  * Check logs: `docker compose logs service-name`
  * Verify configuration: `docker compose config`
  * Check port conflicts
  * Verify image exists and is accessible
  * Check volume permissions

===== Port Already in Use =====

**Symptoms:**
  * Caddy won't start
  * Port conflict errors

**Troubleshooting:**
  * Check what's using ports 80 and 443: `sudo netstat -tulpn | grep :80`
  * Stop conflicting services
  * Use different ports if needed
  * Check for other web servers running

===== Configuration Errors =====

**Symptoms:**
  * Caddy won't start
  * Configuration errors in logs

**Troubleshooting:**
  * Validate Caddyfile: `docker exec caddy caddy validate --config /etc/caddy/Caddyfile`
  * Check for syntax errors
  * Verify file paths in volumes
  * Check for typos in domain names

===== References =====

  * [[https://jamongx.com/caddy-reverse-proxy-docker-https-guide/|Setting Up Caddy Reverse Proxy with Automatic HTTPS (Docker)]]

===== See Also =====

  * [[hosting:caddy:start|Caddy Overview]]
  * [[hosting:caddy:setup|Caddy Setup]]

Last updated: 2026-06-19
  * [[hosting:start|Return to hosting]]