Troubleshooting

Symptoms first. Each section says what to look at, what the usual cause is, and what to do about it.

Where to look#

Three places, in this order:

1. The certificate itself - a failed job surfaces the authority's or the agent's error inline, in plain language. Start here; it is usually the whole answer.
2. Manage > Jobs - the full attempt history for that certificate, including the earlier automatic retries.
3. The agent's own log files on the host - the exact output of a reload command, the path a file was written to, the raw response from a DNS provider's API. See Monitoring.

Jobs retry automatically up to three times before they are marked failed, so a job in that state has genuinely failed three times. A single transient error resolves itself.

Domain verification will not complete#

Almost always propagation. The _aethercert-challenge TXT record has been created but the resolver aethercert uses has not seen it yet. Check it from outside your own network:

dig +short TXT _aethercert-challenge.example.com

If that returns nothing, the record is not published yet - wait and press Verify again. If it returns a different value than the dashboard shows, an old challenge record is still in place; remove it.

Other causes, in order of likelihood:

A job failed on DNS-01#

"zone lookup failed" or a permissions error#

The credential on the domain does not have access to that exact zone. Two things to confirm:

• The credential's scope. Cloudflare in particular needs both Zone:DNS:Edit and Zone:Zone:Read - Zone:Read is what looks the zone ID up before Edit can create the record. A token with only Edit fails here.
• The certificate's domain selection. The hostnames in the common name and SANs must fall under the domain you selected on the job. A mismatch between the two is the most common cause of this error by a wide margin.

Credentials are tested when you save them, so a credential that worked at save time and fails now has usually been revoked or rotated at the provider.

The certificate covers a hostname in a different zone#

Each domain carries its own DNS credentials. A certificate whose SANs span two zones needs both added as domains, each with a working provider.

It works for the apex but not a subdomain#

If internal.example.com is delegated to a separate zone, add it as its own domain with credentials for that zone.

A job failed on HTTP-01#

Wildcards cannot use HTTP-01 at all. That requires DNS-01.

An agent shows as disconnected#

Work down this list:

systemctl status aethercert-agent

curl -sS -o /dev/null -w '%{http_code}\n' https://your-app.example.com

If the binary itself is missing or was quarantined by endpoint protection, repair it:

.\aethercert-installer-windows-amd64.exe repair --redownload

The certificate issued but the service is still serving the old one#

The certificate reached the host and the reload command reported success, but the service did not actually pick it up.

On nginx, the usual cause is key permissions. nginx workers run as an unprivileged user; a key written root-only cannot be read by them, so the reload succeeds while nginx carries on with the old certificate. The NGINX preset handles this by parsing the user directive out of nginx.conf and granting that user read access - if you are using the Custom preset instead, that handling is not applied. Either switch to the NGINX preset or handle the permissions in your own reload command.

Also worth checking:

• The service reads certificates from the paths the deploy target actually writes to.
• The reload command is a reload, not a no-op. systemctl reload on a unit with no reload directive exits 0 without doing anything.
• On IIS, the binding exists and points at the site you expected.

A deploy target fails#

The CA connector pairs but nothing issues#

The connector installs and pairs using its own credentials, but signing needs rights on the CA that a default LocalSystem install does not have. Check both:

• Enroll on the certificate template.
• Issue and Manage Certificates on the CA itself.

By default the connector authenticates as the machine account, which usually has neither. Grant them, or reinstall with --service-account and grant them to a dedicated account. See Service account rights.

If the domain has more than one CA, auto-detection does not choose one - name it with --ca-config "<CAHostName>\<CAName>".

The certificate has the wrong subject#

On AD CS, a subject-from-Active-Directory template makes the CA build the subject from the directory and ignore what was requested. The certificate job form warns about this inline. Use a template that takes the subject from the request.

The related case is a client-authentication template used for a server certificate: it issues successfully and is then rejected for TLS server authentication.

A policy shows a member as "not applied"#

Three legitimate reasons, all reported on the policy's page:

Fix the cause and press Apply now. It is idempotent, so it is always safe to press.

Something is refused because of a plan limit#

The message names the limit. Counting limits refuse the next object and leave existing ones alone; capability limits disable the control with an upgrade hint rather than hiding it. See Plans and limits.

The case that surprises people is a downgrade: existing certificates keep renewing, but one using an authority or key type the lower plan does not allow will fail at its next reissue rather than at the moment of the downgrade.

Rate limits from the authority#

Let's Encrypt's production limits are generous but finite, and repeatedly reissuing the same names while getting a deploy target right is the usual way to hit them. The error comes from the authority and names the limit.

Add Let's Encrypt's staging directory as a second authority and point test certificates at it. Staging certificates are not publicly trusted, which is what makes them safe to burn through.

Still stuck#

Open Help > Support in the dashboard. It routes you to whoever is responsible for your account - aethercert directly, or your MSP if your workspace is one they manage. Include the certificate's common name and the error text from the failed job; that is usually enough to answer without a round trip.