Troubleshooting

Diagnosing failed certificate jobs, DNS-01, HTTP-01 and TLS-ALPN-01 errors, disconnected agents, deploy target failures, CA connector problems and plan-limit refusals.

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:

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.
Manage > Jobs - the full attempt history for that certificate, including the earlier automatic retries.
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:

Cause	Fix
The record was created at the wrong level - `_aethercert-challenge.example.com.example.com`	Most DNS interfaces append the zone automatically. Enter only `_aethercert-challenge`.
The zone is delegated elsewhere	Publish the record in the zone that actually answers for the name.
CAA records forbid the authority	Not a verification failure, but it will block issuance later. Check `dig CAA example.com`.

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

Symptom	Cause
Connection refused or timed out	The host is not reachable from the internet on port 80. HTTP-01 requires that; DNS-01 does not. If the public port 80 is forwarded to a different local port (a firewall/NAT rule), set that under the agent's edit page (Standalone challenge ports) instead of switching challenge type - otherwise connect a DNS provider and switch to DNS-01.
"address already in use"	Something already owns port 80. Configure the deploy target's HTTP-01 webroot so the challenge is served by the existing web server instead of the agent binding the port.
404 on the challenge path	The webroot is set but points at a directory the web server does not serve from.
Works for one name, fails for another	Every name on the certificate is validated separately. All of them must be reachable.

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

A job failed on TLS-ALPN-01

Symptom	Cause
Connection refused or timed out	The host is not reachable from the internet on port 443. If the public port 443 is forwarded to a different local port, set that under the agent's edit page (Standalone challenge ports) - otherwise switch to DNS-01 or HTTP-01.
"address already in use"	Something already owns port 443 - a web server, reverse proxy, or another certificate's deploy target serving HTTPS. Unlike HTTP-01, TLS-ALPN-01 has no webroot mode: it always needs sole use of the port for the duration of the challenge, so this host cannot use it while something else terminates TLS on 443. Use HTTP-01's webroot mode or DNS-01 instead.
Works for one name, fails for another	Every name on the certificate is validated separately. All of them must be reachable on port 443.

Wildcards cannot use TLS-ALPN-01 at all. That requires DNS-01.

Both of the above are caught upfront now: creating or editing a certificate with either challenge type checks reachability before the job is even created and explains exactly which name/port is the problem, rather than only surfacing once a job has already been dispatched and failed. See Network requirements for the full connectivity picture.

An agent shows as disconnected

Work down this list:

On Windows, check the `AetherCertAgent` service in Services. If it is stopped, start
it and look at why it stopped in the agent's log.

The agent only makes outbound HTTPS connections, so no inbound rule is required.
What does sometimes block it is an egress firewall or a proxy the agent's
environment does not know about.

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

Target	Common cause
Windows store / IIS	The service account is not a local administrator.
Exchange / ADFS	The agent is not running on that server, or the management tooling is not installed. aethercert does not install it.
Docker	The agent's service account cannot reach the Docker socket. On Linux that means `docker` group membership.
NetScaler	Wrong Nitro credentials, or a management endpoint serving a certificate the agent does not trust - tick allow self-signed TLS only if that is genuinely the situation.
Custom script	The script is not in the agent's scripts directory, or is not executable. Content is never uploaded - it must already be on the host.

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:

Reason	Fix
The member's OS cannot run the policy's deploy target - a Linux agent under a Windows-store policy	Split the group, or use a policy whose target suits both.
The agent has not reported a hostname yet, so the common name template cannot resolve	Wait for its first check-in.
The resolved hostname is not covered by a verified domain with a DNS provider configured	Add or fix the domain.

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

Check status.aethercert.com first if several unrelated things fail at once - that rules out a platform-side incident before you go looking on the host.

Otherwise 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.

On this page