Troubleshooting
The most common situations you run into when issuing, deploying and renewing a Let's Encrypt certificate β always cause β fix. Linux commands are bash (with sudo), Windows commands are PowerShell run as Administrator. The generated ZIP contains verify.sh / verify.ps1, which perform most of the checks below for you, and a runbook.html with the procedure for your exact scenario.
How to verify the certificate works
Linux / macOS (openssl, curl)
HOST=example.com; PORT=443
# Who issued the certificate, for whom and until when
openssl s_client -connect $HOST:$PORT -servername $HOST -showcerts </dev/null 2>/dev/null \
| openssl x509 -noout -dates -subject -issuer
# Chain: the server must send 2+ certificates (leaf + intermediate)
openssl s_client -connect $HOST:$PORT -servername $HOST -showcerts </dev/null 2>/dev/null \
| grep -c 'BEGIN CERTIFICATE'
# HTTPS from a client's point of view (no -k! if curl complains about the certificate, something is wrong)
curl -vI https://$HOST:$PORT/
Expected: issuer contains O = Let's Encrypt, notAfter is ~90 days after issuance, certificate count β₯ 2, curl does not report SSL certificate problem.
Windows (PowerShell)
$h = 'example.com'; $p = 443
Test-NetConnection $h -Port $p # TcpTestSucceeded : True
Invoke-WebRequest -Uri "https://${h}:${p}/" -UseBasicParsing | Select-Object StatusCode
# Which certificate the server actually sends
$tcp = New-Object Net.Sockets.TcpClient($h, $p)
$ssl = New-Object Net.Security.SslStream($tcp.GetStream(), $false,
[Net.Security.RemoteCertificateValidationCallback]{ $true })
$ssl.AuthenticateAsClient($h)
[Security.Cryptography.X509Certificates.X509Certificate2]$ssl.RemoteCertificate |
Format-List Subject, Issuer, NotAfter
$tcp.Close()
If you have openssl (e.g. from Git for Windows): '' | openssl s_client -connect ${h}:${p} -servername $h -showcerts.
Online
- SSL Labs Server Test β only for a publicly reachable server on port 443. You want an A/A+ grade and "Chain issues: None".
- Watch the expiry yourself: the ZIP contains an
.icsexpiry reminder for your calendar (Let's Encrypt no longer sends expiry e-mails).
Renewal
Linux (certbot)
sudo certbot renew --dry-run # rehearses a renewal against the staging server, changes nothing
sudo certbot certificates # what is issued and until when
systemctl list-timers 'certbot*' --no-pager # the timer (Debian/Ubuntu/RHEL); Alpine: crontab -l
sudo tail -n 50 /var/log/letsencrypt/letsencrypt.log
After a renewal the web server is reloaded by the deploy hook (/etc/letsencrypt/renewal-hooks/deploy/reload.sh, or --deploy-hook with cron). If the timer is not running: sudo systemctl enable --now certbot.timer.
Windows (win-acme)
& 'C:\Program Files\win-acme\wacs.exe' --list # renewals, next due date, installation script
& 'C:\Program Files\win-acme\wacs.exe' --renew --test # rehearsal against staging (renew-test.ps1)
Get-ScheduledTask -TaskName 'win-acme*' | Get-ScheduledTaskInfo |
Format-List TaskName, LastRunTime, LastTaskResult, NextRunTime
Get-ChildItem "$env:ProgramData\win-acme" -Recurse -Filter '*.log' |
Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 50
If the Scheduled Task is missing or disabled: & 'C:\Program Files\win-acme\wacs.exe' --setuptaskscheduler.
Most common failures
Port 80 not reachable from the internet (HTTP-01)
Symptom: Timeout during connect (likely firewall problem), Connection refused, win-acme "validation failed".
Cause: firewall, NAT without a port forward, ISP blocking port 80, web server listening on localhost only.
Fix: test from outside (mobile data, another network), not from the LAN:
curl -I http://example.com/.well-known/acme-challenge/test # expect a 404 from your server, not a timeout
Open the port (ufw allow 80/tcp, firewall-cmd --permanent --add-service=http && firewall-cmd --reload, Windows New-NetFirewallRule -DisplayName "HTTP-01" -Direction Inbound -LocalPort 80 -Protocol TCP -Action Allow) and add a port forward on the router. If port 80 cannot be opened, answer "port 80 reachable from the internet: no" in the wizard β DNS-01.
CAA record blocks letsencrypt.org
Symptom: CAA record for example.com prevents issuance.
Cause: the domain (or a parent domain) has a CAA record that does not list Let's Encrypt.
Fix:
dig CAA example.com +short # check the parent domains too
Add 0 issue "letsencrypt.org" (for wildcards also 0 issuewild "letsencrypt.org"), or remove the restrictive CAA. Wait for the TTL to expire.
DNS-01: the TXT record did not propagate in time
Symptom: Incorrect TXT record / No TXT record found at _acme-challenge.example.com, although the record is in Cloudflare.
Cause: validation ran before the record reached the authoritative servers.
Fix: in issue.sh raise --dns-cloudflare-propagation-seconds 30 to 60β120 (the value is also saved to /etc/letsencrypt/renewal/<domain>.conf for renewals). win-acme: raise Validation.PreValidateDnsRetryCount / PreValidateDnsRetryInterval in settings.json. Check:
dig TXT _acme-challenge.example.com @1.1.1.1 +short
Delete stale _acme-challenge TXT records left over from manual attempts. Authentication error (10000) = wrong/expired token or a token without rights to this zone β Cloudflare token.
Let's Encrypt rate limits
Symptom: too many failed authorizations recently, too many certificates already issued.
Cause: Let's Encrypt limits β 5 failed validations per account/hostname/hour, 50 certificates per registered domain per week, 5 duplicate certificates (same set of names) per week.
Fix: rehearse first β the "Dry run first" toggle in step 4 adds --dry-run (certbot) / --test (win-acme); the staging server has much higher limits. After a failure fix the cause first, do not retry in a loop; after an hour you can try again. Overview: letsencrypt.org/docs/rate-limits.
Wildcard requires DNS-01 and does not cover the apex
Symptom: HTTP-01 for *.example.com fails; a certificate for *.example.com does not work on https://example.com.
Cause: wildcards can only be validated with DNS-01. *.example.com covers www.example.com or api.example.com, but not example.com itself nor a.b.example.com.
Fix: DNS-01 (Cloudflare or manual TXT) and put both names into the certificate: *.example.com and example.com. Mind the paths: certbot names the lineage without the *. β /etc/letsencrypt/live/example.com/ (the generated scripts account for this).
Windows: IIS already holds port 443 β use another port for mServer
Symptom: netsh http add sslcert fails with error 183 ("Cannot create a file when that file already exists") or mServer does not come up on 443.
Cause: port 443 belongs to IIS (or another http.sys application).
Fix: give mServer a different port (444, 8443) both in the HTTPS tab and in the wizard. netsh http show sslcert shows who holds which port.
Windows: certificate without a private key / netsh error 1312
Symptom: SSL Certificate add failed, Error: 1312 β A specified logon session does not exist.
Cause: the certificate in the store has no private key, or it is in CurrentUser\My instead of LocalMachine\My.
Fix:
Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.HasPrivateKey } |
Format-Table Thumbprint, Subject, NotAfter
If the right certificate is missing, run issue.ps1 again (it stores into LocalMachine\My with the key); always bind with certstorename=MY.
PowerShell blocks downloaded .ps1 files
Symptom: β¦ cannot be loaded because running scripts is disabled or β¦ is not digitally signed.
Cause: files from the internet carry the "Mark of the Web" and the execution policy rejects them.
Fix:
Unblock-File .\*.ps1
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
win-acme: Cloudflare plugin does not match the wacs.exe version
Symptom: Unable to find validation plugin cloudflare, Could not load file or assembly β¦.
Cause: plugin.validation.dns.cloudflare.*.zip comes from a different release than wacs.exe.
Fix: install.ps1 downloads the plugin from the same release as wacs.exe β after a manual win-acme update run it again (optionally .\install.ps1 -Version vX.Y.Z). Check: Get-ChildItem 'C:\Program Files\win-acme' -Filter '*Cloudflare*'.
HAProxy needs a concatenated PEM
Symptom: after a renewal HAProxy still serves the old certificate; unable to load SSL private key.
Cause: HAProxy reads fullchain + private key from one file; certbot only renews /etc/letsencrypt/live/β¦.
Fix: the wizard's renewal hook rebuilds the concatenated PEM from $RENEWED_LINEAGE on every renewal and reloads HAProxy. By hand:
sudo sh -c 'umask 077; cat /etc/letsencrypt/live/example.com/fullchain.pem /etc/letsencrypt/live/example.com/privkey.pem > /etc/haproxy/certs/example.com.pem'
sudo haproxy -c -f /etc/haproxy/haproxy.cfg && sudo systemctl reload haproxy
"Too many redirects" / HTTP-01 behind the Cloudflare proxy (orange cloud)
Symptom: validation ends in a redirect, Too many redirects, 403/520 from Cloudflare; standalone mode never receives a connection.
Cause: with the proxy on (orange cloud) HTTP terminates at Cloudflare β "Always Use HTTPS", the cache or Cloudflare's own certificate get in the way and the challenge never reaches your server.
Fix: use DNS-01 (Cloudflare token) β the simplest option, and it works for wildcards too. Or temporarily switch the record to the grey cloud (DNS only), issue the certificate, then turn the proxy back on; set the Cloudflare SSL/TLS mode to Full (strict). Alternatively exclude /.well-known/acme-challenge/* from "Always Use HTTPS" and the cache with a rule.
certbot "unauthorized" / challenge file not served (webroot)
Symptom: Invalid response from http://example.com/.well-known/acme-challenge/β¦: 404 (or 301/403).
Cause: wrong webroot path (a different vhost answers for the domain), rewrite rules (SPA catch-all, redirect to HTTPS), blocked "dot" directories.
Fix: verify that a file from the webroot is visible from outside:
WEBROOT=/var/www/html
sudo mkdir -p $WEBROOT/.well-known/acme-challenge
echo ok | sudo tee $WEBROOT/.well-known/acme-challenge/test >/dev/null
curl -i http://example.com/.well-known/acme-challenge/test # expect 200 and "ok"
Find the real root with sudo nginx -T | grep -B3 'root ' / apachectl -S. For nginx an exception helps:
location ^~ /.well-known/acme-challenge/ { root /var/www/html; default_type text/plain; }
If it cannot be untangled, use standalone (stop the web server for a moment) or DNS-01.
RHEL / Alma / Rocky: EPEL missing
Symptom: No match for argument: certbot.
Cause: certbot lives in EPEL, not in the base repositories.
Fix:
sudo dnf install epel-release # Alma / Rocky / CentOS Stream
# plain RHEL: epel-release is not in the repositories, install it from the URL
sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
sudo dnf install certbot python3-certbot-dns-cloudflare # + python3-certbot-nginx / -apache
On RHEL you usually also need subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms.
Alpine Linux β notes
Cause: Alpine has neither systemd nor bash by default, and some packages live in the community repository.
Fix:
apk add bash curl openssl certbot py3-certbot-dns-cloudflare # the community repo must be enabled in /etc/apk/repositories
rc-update add crond default && rc-service crond start # renewal via cron, not a timer
crontab -l # the line from cron-entry.txt
rc-service nginx reload # OpenRC instead of systemctl
The wizard's scripts are for bash β run them with bash issue.sh, not sh.
The certificate renewed, but the server still sends the old one
Cause: the web server was not reloaded (hook failed), HAProxy has a stale concatenated PEM, on Windows the binding still points to the old thumbprint.
Fix: sudo systemctl reload nginx (apache2/haproxy/caddy) and check the hook in /var/log/letsencrypt/letsencrypt.log; Windows: netsh http show sslcert and wacs.exe --list (the renewal must show an installation script); for mServer see the dedicated guide. Then re-run the verification from the top of this page.