πŸ” Let's Encrypt Wizard
Česky ← Back to the wizard

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

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.