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's
environment does not know 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.
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. |
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.
Challenges 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.