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. Start here; it is usually the whole answer.
Manage > Jobs. The full attempt history for that certificate, including the earlier automatic retries and which step failed.
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 Logs and diagnostics.

A job retries automatically up to three attempts in total, so a job in failed state has genuinely failed. A failure the agent classified as permanent - bad credentials, an object name the target does not recognise - stops on the first attempt rather than repeating an identical failure three times.

The job form refuses to save

The certificate job form validates before it creates anything, and each refusal names the fix.

Message	Cause
"DNS-01 requires a domain with a DNS provider configured"	Choose HTTP-01 or TLS-ALPN-01, pick a different domain, or configure a provider under Manage > Domains.
"internal domains require an Internal CA (REST)"	An internal domain has no ACME reachability. Only an internal REST authority can issue for it.
"This deploy target doesn't run on ..."	An agent runs one operating system. Choose a matching preset, or a third-party target that talks to a remote API.
"This deploy target needs a certificate with both Server and Client Authentication"	Let's Encrypt and PSW Group issue server-auth certificates only. Use an ACME CA pointed at a private issuer, or an Internal CA (REST).
"Job cannot be executed" with a challenge, a name and a reason	The upfront reachability probe could not open port 80 or 443 for that name. See HTTP-01 below.
"agent groups require the Standard plan or higher"	Groups and policies are a Standard feature.

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

Nothing returned means the record is not published yet - wait and press Verify again. A different value than the dashboard shows means 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. Enter only `_aethercert-challenge`.
The zone is delegated elsewhere	Publish the record in the zone that actually answers for the name.
"This domain is already registered to another organization"	Domain names are globally unique. It has to be removed from that organization first.
CAA records forbid the authority	Not a verification failure, but it blocks issuance later. Check `dig CAA example.com`.

A job failed on DNS-01

A zone lookup or 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 have to 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 tried against the provider's API when you save them, so one that worked then 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.

Propagation checks fail on an IPv4-only or IPv6-only agent

An agent pinned to one stack bypasses the system resolver for the propagation check and queries Cloudflare's public resolvers directly. An environment that locks egress DNS to an internal resolver has to allow those two addresses as well - see Network requirements.

A job failed on HTTP-01

Symptom	Cause
Connection refused or timed out	The host is not reachable from the internet on port 80. If the public port 80 is forwarded to a different local port, set that under Manage > Agents > Edit (standalone challenge ports); otherwise connect a DNS provider and switch to DNS-01.
"address already in use"	Something already owns port 80. Set the deploy target's `http01_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 have to 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. Set a standalone port override if NAT forwards it, otherwise switch to DNS-01 or HTTP-01.
"address already in use"	Something already owns port 443 - a web server, a reverse proxy, 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.
Works for one name, fails for another	Every name is validated separately.

Both of the above are caught upfront: creating or editing a certificate with either challenge type probes reachability before the job is created and names the exact name and port that failed.

An agent shows as offline

Work down this list.

Is the service running?
```
systemctl status aethercertagent
```
On Windows, check the AetherCertAgent service in Services. If it is stopped, start it and look at the agent's log for why it stopped.
Can the host reach the control plane?
```
curl -sS -o /dev/null -w '%{http_code}\n' https://api.aethercert.com/api/healthz
```
The agent only makes outbound HTTPS connections. What blocks it is an egress firewall or a proxy the agent's environment does not know about.
Has it been revoked? A revoked agent cannot authenticate and never will again. Use Re-register on the agent to mint a fresh token, or re-enroll the host.
Is it just idle? An agent is called offline only once it is past twice its own check-in interval. On the default 3-hour cadence that is 6 hours, so one missed interval is not the signal.

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 still serves the old one

The certificate reached the host and the reload command reported success, but the service did not 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 used the Custom preset instead, that handling is not applied - either switch presets 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.
On PAN-OS, the commit finished. An import without a commit does not take effect.

A deploy target fails

Target	Common cause
Windows store, IIS	The service account is not a local administrator.
Exchange, AD FS, SQL Server, Skype for Business	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, F5, Kemp, FortiGate, FMC	Wrong 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.
Sophos Firewall	The API is disabled by default. Enable it under WebAdmin > Backup & firmware > API, allow-list the agent's address, and unbind the certificate from any running service first.
Kubernetes	The ServiceAccount token cannot create or update Secrets in that namespace.
Custom script	The script is not in the agent's scripts directory, is not owned by root, is group- or world-writable, or does not have the right extension - `.sh` on Linux, `.ps1` on Windows. Content is never uploaded; it has to already be on the host.

A message of the form "rejected the configured credentials (HTTP 401)" is classified as permanent and does not retry. Fix the credential and press Retry.

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, for revocation.

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. Run aethercert-ca-connector preflight on the host - it reports each item as OK or names the exact step still missing. See The CA connector.

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"

The reason is on the row.

Reason	Fix
The member's OS cannot run the policy's deploy target	Split the group, or use a target that suits both.
The agent is revoked	Re-register it, or remove it from the group.
The agent has not reported a hostname yet, so the template cannot resolve	Wait for its first check-in.
The resolved hostname is not covered by a verified domain with a DNS provider	Add or fix the domain.
"this policy is disabled - enable it to apply it"	Enable the policy first.

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

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 fails 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; the job schedules its next attempt rather than retrying immediately.

Add Let's Encrypt's staging directory as a second authority and point test certificates at it.

Symptom	Cause
"invalid email or password" after several tries	The account may be locked. Ten failed attempts lock it for 5 minutes, and each further failure doubles the wait. Fifteen minutes with no attempt resets the counter.
Microsoft sign-in fails	See the single sign-on troubleshooting table.
Lost the authenticator app	An owner resets it from Settings > Organization > Members.
"second factor required" on an action that used to work	Irreversible actions re-check multi-factor server-side. Complete the challenge.

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