Diagnosing Yunohost Domain DNS and Let's Encrypt Certificate Failures

The problem and what to check first

After you add a domain to Yunohost, browsers show certificate warnings and the admin panel reports no installed Let's Encrypt certificate. `yunohost diagnosis` may flag DNS or certificate categories. The useful takeaway: most failures come from a mismatch between the public DNS zone at your registrar and the records Yunohost expects, or from port 80 being unreachable for the HTTP-01 challenge. HTTP-01 is a Let's Encrypt validation method that requires port 80 to be reachable from the internet. Do not disable HTTPS or ignore warnings; that hides the fault and can break app trust and HSTS. HSTS is a browser policy that remembers HTTPS-only sites.

Recognizable condition

You are likely in this scenario if one or more of the following are true:

• Browsers show "Your connection is not private" or certificate mismatch warnings for the domain.
• `yunohost domain cert-status ` reports no installed certificate or an expired one.
• `yunohost diagnosis` returns failed categories related to DNS, firewall, or certificates.
• Email apps cannot connect or mail delivery fails after DNS changes.

Cause and diagnostic table

Observed condition	Likely cause	Check command
`cert-status` shows no certificate; diagnosis flags DNS	Public DNS A/AAAA/MX/TXT records do not match `yunohost dns-conf `	`dig +short A ` and compare to `yunohost dns-conf `
Lookup works sometimes, fails at other times	DNS propagation delay or TTL not yet expired. TTL is time-to-live, how long resolvers cache a record.	Query multiple resolvers; wait for TTL
Certificate logs show timeout on port 80	HTTP-01 challenge blocked by firewall, app conflict, or missing listener	Check listeners on ports 80/443; review firewall rules
Challenge error mentions DNS-01	DNS-01 method not supported or credentials missing	Review `cert-status` output and Let's Encrypt logs
Expiry date is past; renewal logs show errors	Renewal timer or cron failure; underlying DNS or port issue persists	Inspect renewal logs and timer/cron status

Ordered checks

Run these on the Yunohost server over SSH. Most commands require root or `sudo`. Replace `` with your actual domain name.

1. Confirm the domain is managed by Yunohost

   Run:

   yunohost domain list

   Required permission: root or sudo. Look for the domain in the list. If it is missing, add it first before diagnosing certificates.

2. Run diagnosis and record failed categories

   Run:

   yunohost diagnosis

   Required permission: root or sudo. Note any failed DNS, certificate, firewall, or mail categories. Capture this output before making changes so you can compare afterward.

3. Compare public DNS with Yunohost configuration

   Run:

   yunohost dns-conf 

   Then query live records from multiple public resolvers:

   dig +short A  @1.1.1.1
   dig +short A  @8.8.8.8
   dig +short MX 
   dig +short TXT 

   MX is the mail exchange record. Required permission: none for `dig`; root or sudo for `yunohost dns-conf`. The public A/AAAA record should match the IP Yunohost expects, and MX/TXT records should match if mail is enabled. One successful lookup is not proof; wait for TTL and check multiple resolvers to avoid a single cached answer.

4. Check certificate status and expiry

   Run:

   yunohost domain cert-status 

   Required permission: root or sudo. Look for an installed certificate, the issuer, and the expiry date. If expiry is in the past or no certificate is listed, proceed to renewal checks.

5. Inspect renewal logs and timer

   Run:

   journalctl -u certbot.timer --no-pager | tail -n 50
   systemctl list-timers | grep cert

   Required permission: root or sudo. Look for recent renewal attempts and errors. Command names and timer units can differ across Yunohost major versions.

6. Verify listeners on ports 80 and 443

   Run:

   ss -tlnp | grep -E ':80|:443'

   Required permission: root or sudo. A process should be listening on port 80 for HTTP-01 challenges and port 443 for HTTPS. If nothing listens on 80, nginx may be stopped or an app may be occupying the port.

7. Check for recent DNS provider or registrar changes

   Review changes made at your DNS host or registrar. If name servers were changed recently, propagation may still be in progress.

Fixes tied to findings

• DNS records missing or wrong: Update the registrar DNS zone to exactly match `yunohost dns-conf `, including MX, SPF, DKIM, and DMARC records if mail is enabled. SPF, DKIM, and DMARC are email authentication records. Wait for the TTL to expire, then re-run diagnosis and cert-status.
• Propagation or TTL delay: Wait for TTL and confirm from multiple resolvers. Do not force repeated issuance while waiting; Let's Encrypt rate limits can temporarily block the domain.
• HTTP-01 blocked: Allow traffic on port 80 through the Yunohost firewall and resolve any app conflict flagged by diagnosis. Then run the supported certificate install command for the domain.
• DNS-01 unsupported: Use a supported challenge method or configure DNS-01 credentials according to your Yunohost version. Do not invent credentials or provider tokens.
• Renewal failure: Correct the underlying DNS or port issue first, then run the supported certificate install or renewal command for the domain. Check `cert-status` afterward for a valid future expiry.
• Mail deliverability at risk: Test mail before and after editing SPF, DKIM, or DMARC. Incorrect records can cause outgoing mail to be rejected.

Root-level commands may restart nginx, Postfix, or Dovecot and briefly interrupt services. Schedule changes during a maintenance window if the server is in production.

Escalation criteria

Escalate to Yunohost support or your DNS provider when:

• DNS is correct and stable across multiple resolvers, but certificate issuance still fails.
• A multi-domain certificate fails for one subject alternative name (SAN) while others succeed. A SAN is an additional domain covered by one certificate.
• `yunohost diagnosis` crashes or reports unknown categories.
• Required changes are at the DNS provider or registrar and you do not have access.
• Production mail deliverability is at risk from SPF, DKIM, or DMARC edits.

Limitations and verification

This guide assumes a current stable Yunohost 11 or 12 line. Diagnosis categories, command names, and certificate renewal internals are version-sensitive and have changed across major releases. Verify command behavior on your installed version before running root commands. This is a conservative draft; confirm behavior on your system before applying changes to production.

Practical verification: capture `yunohost diagnosis` and `yunohost domain cert-status ` before and after the change. After a fix, confirm the certificate shows a valid future expiry and diagnosis no longer flags DNS or certificate categories. Compare `yunohost dns-conf ` with the live registrar zone before and after edits, including mail-related records.

On a disposable VM, you can add a test subdomain, break one DNS record, and confirm that the diagnosis category and `cert-status` change as described. Do not run destructive tests on production mail domains.