Agent troubleshooting
Diagnosing an agent on the host itself: the service will not start, enrollment fails, the binary was quarantined, a deploy step fails, the connector cannot issue.
This page is about the host. For a failed certificate job seen from the dashboard, start at Troubleshooting.
First three commands
aethercert-installer statusWhat is installed, each component's version and service state, whether its binary and config are actually present, and which control plane it points at. Exits 0 either way.
systemctl status aethercertagent
journalctl -u aethercertagent -n 100On Windows, the AetherCertAgent service in services.msc.
tail -n 200 /etc/aethercert-agent/agent/logs/$(date -u +%F).logC:\ProgramData\aethercert\agent\logs\ on Windows. Grep for [ERROR] and [WARN] first.
The install fails
| Symptom | Cause |
|---|---|
| "run this as root" / "requires administrator" | The installer writes to system paths and registers a service. sudo on Linux, an elevated prompt on Windows. |
| "the download does not match its published checksum" | The bootstrap script refused to run what it downloaded. Nothing was installed. Retry; if it repeats, the CDN path or a proxy in between is rewriting the response. |
| "the release signature ... does not verify" | Fatal, and always. Do not work around it. |
"no published build for <arch>" | Only linux/amd64 is published today. |
| "invalid enrollment token", "enrollment token expired", "enrollment token already used" | A token is valid for one hour, and a single-provision token for one host. Generate a new one. |
| The command returns immediately on Windows and nothing seems to happen | The installer is a GUI-subsystem executable, so PowerShell does not wait for it. Use Start-Process -Wait -NoNewWindow, or pipe the output. |
"1069" or a bare start failure with --service-account | Current builds report the real reason - wrong password, disabled account, or a Deny log on as a service policy. If you see a bare 1069, the installer is older than that check; check those three. |
The whole run is written to the installer's own log - see File locations.
The service will not stay running
-
Read the log. The agent writes to its own file as well as stderr, so a Windows service failing at startup is still diagnosable.
-
Is
config.jsonthere and readable?aethercert-installer statussays. A missing or truncated config is the common cause after a partial uninstall. -
Are the credentials still accepted? A revoked agent authenticates and is refused. The log says so. Use Re-register in the dashboard rather than reinstalling.
-
Was the binary quarantined? Endpoint protection removing the executable leaves the service registered and pointing at nothing. Repair it:
.\aethercert-installer-windows-amd64.exe repair --redownload
The agent runs but never appears in the dashboard
An agent appears the first time it checks in, not when the token is created.
curl -sS -o /dev/null -w '%{http_code}\n' https://api.aethercert.com/api/healthzIf that fails from the host, the problem is egress: a firewall, or a proxy the agent was
not told about. The agent needs outbound HTTPS to api.aethercert.com and
cdn.aethercert.com - two separate hosts, and allowing one does not allow the other. A
proxy goes into config.json (see Outbound proxy),
or in one step with aethercert-installer repair --proxy <url>; the log names the proxy in
effect at every start (outbound proxy: …).
If it succeeds and the agent still does not appear, the log will say whether enrollment was rejected.
The host never updates
| Check | |
|---|---|
| Is the Update Service installed? | aethercert-installer status. An install with --no-update-service, or a container running aethercert-agent run directly, has nothing that can update it. |
| Is automatic update on for this agent? | Manage > Agents > Manage > Settings. Off pins the version deliberately. |
| Is a release actually offered to this host? | A staged rollout, a channel, or a minimum upgradable version can all mean "no update for you, yet". See Updates. |
| Did it try and fail? | The Update Service's own log, and the event log's update.failed / update.rolled_back entries. |
Force one by hand, elevated:
aethercert-update-service update --agentA deploy step fails
The job's error text comes straight from the connector that ran it, and the agent's log has the full context - the path it wrote to, the reload command's own output, the target's HTTP response.
| Symptom | Cause |
|---|---|
| "custom_script_linux requires a .sh script_name" | Extension mismatch. .sh on Linux, .ps1 on Windows. |
| "script_name ... must be a bare filename, not a path" | The dashboard passes a filename; the agent resolves it against its own scripts directory. |
| "script must be owned by root" / "must not be group- or world-writable" | The permission gate. chown root: <script> and chmod 750. |
| "custom script ... did not finish within 1m0s" | The 60-second cap. A hook that needs longer should hand off to something asynchronous. |
| "rejected the configured credentials (HTTP 401)" | Classified as permanent, so it does not retry. Fix the credential and press Retry. |
| A reload command that "succeeds" while the old certificate is still served | See the reload section. |
| "connect to docker" | The service account cannot reach the socket or named pipe. |
| "remote error: tls: handshake failure" on a Citrix NetScaler target | No ECC curves on the NetScaler's management service, so it shares no cipher with the agent. See AEK443001. |
The CA connector pairs but nothing issues
Run the readiness check on the host:
.\aethercert-ca-connector.exe preflightIt names the exact step still missing. The usual answer is the two CA rights - Enroll on the template and Issue and Manage Certificates on the CA - which a default LocalSystem install authenticates for as the machine account, and which that account usually does not have. 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>".
A check reported as review this rather than OK means a permission held through a group the check cannot expand offline. That is not a failure; confirm it in the console.
If jobs fail with "the server's TLS key does not match the pinned key", the agent reached
something that is not the connector, or the connector has a new key that the control plane
has not heard about yet. Compare the connector's log line tls: listener key sha256:…
with the newest CA connector reported … TLS key entry in the event log. A new key is
reported at the connector's next check-in, right after it starts; if the check-in fails,
the connector's log says why. If the keys match but agents still refuse, something between
them answers in the connector's place.
The certificate connector stays offline: "reported keys other than the ones registered"
Its log shows check-ins failing with this connector reported keys other than the ones
registered for it, and the event log has reported keys other than its registered ones.
aethercert recorded the connector's keys at its first check-in after enrollment and does
not accept others. Either the server was rebuilt or restored without its state directory -
then create an enrollment token for the connector and install again - or the connector's
secret is in someone else's hands: treat it as a compromised credential, enroll again, and
look at where config.json went.
A deployment fails on Linux after the 2026.10.7.0.0 update
From 2026.10.7.0.0 every systemd unit carries a sandbox, which takes effect at the
service's next restart (see systemd sandbox).
The agent's only closes kernel interfaces that no deployment uses, so this should not
happen. If a deploy script now fails with "Operation not permitted" where it used to
work - loading a kernel module, setting the clock, reading dmesg - switch the setting off
for this host with a drop-in, and tell us what the script does:
sudo systemctl edit aethercertagent # e.g. [Service] ProtectKernelModules=no
sudo systemctl restart aethercertagentChallenges fail on a single-stack agent
An agent set to IPv4-only or IPv6-only bypasses the system resolver for DNS-01 propagation checks and queries Cloudflare's public resolvers directly. An environment that locks egress DNS to an internal resolver has to allow those addresses too - see Network requirements.
The setting also does not apply to Route 53 DNS-01, which uses the AWS SDK's own client, or to the PowerShell-based Windows deploy targets, which bypass the agent's networking entirely.
Getting help
Include the agent's version (aethercert-agent version), the output of
aethercert-installer status, and the relevant lines from the day's log. Open
Help > Report a Bug in the dashboard.