Diagnosing Let's Encrypt SSL Failures in Yunohost

Problem and takeaway

You attempt to issue or renew a Let's Encrypt certificate for a domain managed by Yunohost, and the admin panel or command line reports failure. Browsers may show certificate warnings, or secure pages may stop loading after expiry.

Takeaway: most failures fall into four groups—DNS does not point to the server, port 80 or 443 is blocked, Let's Encrypt rate limits were reached, or Yunohost did not reload its web server after renewal. Match the symptom to the check, then apply the matching fix.

Let's Encrypt is a free certificate authority that issues TLS certificates through the ACME protocol. TLS is the encryption layer behind HTTPS. An A or AAAA record maps a domain to an IPv4 or IPv6 address. The ACME challenge is a temporary file under /.well-known/acme-challenge/ that Let's Encrypt fetches to prove you control the domain.

Assumptions and required access

This guide assumes Yunohost is using the default HTTP-01 challenge, which requires inbound port 80. It does not cover wildcard certificates, which require DNS-01 validation. CLI names and paths can change between Yunohost releases; check your installed version before running state-changing commands.

Run server-side commands from a shell on the Yunohost host as an administrative user with sudo. Run network checks from a machine outside your local network. Replace example.com with your domain and 203.0.113.10 with your server's public IP. Do not paste private keys, account credentials, or unredacted logs into support tickets or public output.

Recognizable conditions and likely causes

Symptom	Likely cause	First diagnostic
Browser certificate error or cert-renew failure	DNS A/AAAA records point to a different IP	dig +short example.com A from an external network returns an unexpected address
Certificate issuance times out	Port 80 or 443 blocked by ISP, router, or firewall	External request to http://example.com/.well-known/acme-challenge/test times out or is refused
Renewal fails with duplicate certificate or rate limited	Let's Encrypt rolling weekly limit reached	ACME error text contains those phrases
Admin panel reports Certificate not trusted after renewal	Nginx still serving the previous certificate	yunohost domain cert-info example.com shows issuer or expiry that does not match the new file
Certificate commands fail with permission or command-not-found errors	Session lacks root/sudo access or Yunohost CLI is not in PATH	id and which yunohost do not confirm administrative access

Ordered diagnostic checks

1. Confirm administrative access

   Run on the Yunohost server:

   id
   which yunohost

   Expected: id shows uid=0(root) or membership in sudo, and which yunohost prints a path such as /usr/bin/yunohost. If either fails, log in as the admin user or use sudo before certificate commands.

2. Confirm DNS points to the server

   Run from an external network or public resolver:

   dig +short example.com A
   dig +short example.com AAAA

   Expected: at least one record matches the server's public IP. If the addresses differ, DNS is the likely cause. Before changing records for a domain that handles mail, verify existing MX and SPF records so you do not interrupt delivery.

3. Confirm HTTP reachability

   Run from outside your network:

   curl -I http://example.com/.well-known/acme-challenge/test

   Expected: an HTTP response such as 404 Not Found means the web server is reachable but the challenge file does not exist yet. Connection timed out or Connection refused means port 80 is blocked or not forwarded to Yunohost.

4. Inspect the current certificate state

   Run on the Yunohost server:

   sudo yunohost domain cert-info example.com

   Expected: the issuer is Let's Encrypt and the expiry date is in the future. If the issuer is missing or the date is in the past, issuance or renewal did not complete successfully.

5. Attempt one controlled renewal

   Run on the Yunohost server:

   sudo yunohost domain cert-renew example.com

   Expected: success or a specific ACME error. Do not repeat this command multiple times in quick succession; repeated attempts can trigger Let's Encrypt rate limits and temporarily block the domain.

Fixes tied to findings

DNS does not point to the server

Update the A and AAAA records at your DNS host or registrar to the server's public IP. Wait for propagation, then re-run the dig check. Rollback: if mail or other services break, revert the records to their previous values.

Port 80 or 443 is blocked

Open inbound port 80 for HTTP-01 validation and port 443 for HTTPS traffic. Adjust router port forwarding, ISP settings, or the host firewall as applicable. If your ISP blocks port 80 and cannot unblock it, HTTP-01 will not work; consider a DNS-01 workflow or a different network, which is outside this guide.

Rate limit reached

Wait for the Let's Encrypt rolling window to clear, typically up to one week. Avoid forcing reissuance while limited. Check cert-info after waiting.

Nginx not reloaded after renewal

Run sudo yunohost domain cert-renew example.com, which normally reloads the web server. If the certificate file is new but the panel still shows the old certificate, reload nginx manually. On many Yunohost releases this is sudo systemctl reload nginx; confirm the command for your release before running it.

Missing administrative access

Log in as an admin user and prefix commands with sudo. If which yunohost returns nothing, use the full path or restore the admin PATH for your shell.

Escalation criteria

• DNS changes do not propagate after 24–48 hours.
• Your ISP blocks port 80 or 443 and cannot be configured to allow them.
• Rate-limit errors persist after waiting a week.
• cert-info shows a valid certificate but browsers still reject it after a reload, which may indicate CAA records, chain issues, or client-side caching.

Verify the result

Open the Yunohost admin web interface, go to the domain certificate page, and confirm an active Let's Encrypt certificate with a future expiry date. Then run:

sudo yunohost domain cert-info example.com

From an external machine, run:

openssl s_client -connect example.com:443 -servername example.com

Confirm the presented certificate matches the expected issuer and validity dates.

Limitations

• Covers HTTP-01 only; wildcard certificates require DNS-01 validation.
• Does not cover custom or self-signed certificates.
• CLI behavior may differ by Yunohost release; verify against your installed version.
• This draft requires current verification against a running Yunohost system before production use.