Documentation
Troubleshooting and FAQ
Common problems with agents, sign-in, scans and SSO, and answers to frequent questions.
Agents
Start with the agent's log: journalctl -u aetherion-agent -f on Linux, sudo tail -f /var/log/aetherion-agent.log on macOS, or %ProgramData%\Aetherion\agent.log on Windows.
| Symptom | Cause and fix |
|---|---|
| Agent stays pending | It is waiting for approval. Approve it on the Agents page. |
| Log says “Registration rejected: the enrolment token is invalid” | The token is wrong, has expired or was rotated, or the agent points at a different server. Copy the current command from Agents → Enroll and reinstall. |
| Installer stops with “checksum mismatch” | The download was cut short or altered on the way, often by a proxy error page or stale cache. Retry; if it keeps happening, check your proxy. |
x509: certificate signed by unknown authority | The agent doesn’t trust the server’s certificate, often because a self-signed certificate was replaced. Re-run the installer so it saves the new one. |
| Job failed with “Job refused: signature does not match” | The agent has a different job-signing key from the server, for example after it was installed against another server. Reinstall it from the dashboard. |
| Job failed with “Job refused: job expired” | The agent was offline for more than 24 hours after the job was sent. Dispatch it again. |
| Job failed with “No result from the agent within 10 minutes” | The agent stopped or lost its connection mid-job. The script may have run, so check the endpoint before re-running. A late result replaces this status. |
| “Update available · reinstall” instead of Update now | The agent is too old to update itself. Re-run the install command once; it keeps its identity and approval. |
| Update failed with “rolled back” | The new version couldn’t start or reach the server, so the agent restored the old one. Automatic updates pause for that agent until someone clicks Update now. |
| Assets missing or out of date | Agents report assets hourly by default, so allow up to an hour. Services that listen only on 127.0.0.1 are not reported. |
| Software shows “not matched” | There is no public vulnerability data for that platform (macOS apps, Windows programs, Fedora, Homebrew). Hover for the reason. |
| A deleted agent doesn’t come back | Current agents remove the enrolment token from their configuration once enrolled, so they don’t re-enrol by themselves. Reinstall to enrol it again. |
Signing in
| Symptom | Cause and fix |
|---|---|
| Locked out after several failed attempts | Too many failed passwords or codes. Wait 15 minutes (or your organisation’s lockout time) and try again. |
| Sent to the profile page after signing in | Your password has expired or was set by an Admin, or your organisation requires two-factor authentication and you haven’t set it up. Complete the step shown. |
| Lost your authenticator and recovery codes | Ask an Admin to use Reset 2FA on Settings → Users. |
| “This account is disabled” | An Admin or your identity provider deactivated the account. Ask an Admin. |
| “Your organization signs in with single sign-on” | Password sign-in is turned off for your account. Use Continue with SSO. |
| Signed out unexpectedly | The session reached its time limit, you changed your password or two-factor settings elsewhere, or an Admin signed you out. |
Single sign-on errors
If SSO fails, the sign-in page URL ends with ?sso_error= and a code:
| Code | Meaning |
|---|---|
expired | The sign-in took longer than 10 minutes or was started in another browser. Try again. |
idp_denied | You cancelled, or your identity provider refused you. Check your assignment to the application there. |
idp_rejected | The provider refused the request: usually a wrong client secret or redirect URI. |
idp_unreachable | The server couldn’t reach the provider. |
invalid_token | The provider’s token failed validation. Check the issuer URL and client ID. |
misconfigured | The issuer doesn’t match the provider’s discovery document, or the configuration is incomplete. |
wrong_domain | Your email’s domain isn’t one of the organisation’s verified domains. |
not_provisioned | No account exists for you and automatic account creation is off. Ask an Admin. |
email_unverified | Your provider says your email address isn’t verified. |
account_conflict | Your email is already used by an account in another organisation. |
account_disabled | Your account is deactivated. |
Scans and findings
| Symptom | Cause and fix |
|---|---|
| Scan rejected with a message about the target | The target isn’t allowed, for example a link-local or cloud-metadata address, or a code scan given something other than an http(s) or git URL. |
| “Valid License Key required” when starting a scan | The instance has no valid licence. Cloud customers: contact us. Dedicated instances: check with your administrator. |
| A scan stays pending | The scanning service is busy or unavailable. If it doesn’t start within a few minutes, contact support. |
| An Info finding ending in “Error”, “Timeout” or “Unreachable” | One tool couldn’t reach the target or finish in time. The other tools still ran; check the target is reachable from the server. |
| The dashboard shows fewer vulnerabilities than Findings | Findings below the severity floor (Settings → System), and Info findings, aren’t counted. |
Frequently asked questions
- Does the agent open any ports or accept incoming connections?
- No. It only makes outbound HTTPS requests to your server.
- Can Holistra run a script on my endpoints without my approval?
- Only users with the Admin or Security Engineer role in your organisation can dispatch scripts, and only to agents you have approved. Every job is signed and the agent rejects anything altered or meant for another organisation. See Remediation scripts.
- What does the agent send to the server?
- Device details (hardware, OS, users, network interfaces, listening ports), security posture checks, installed software, its attack surface (startup items, accounts, SSH keys, sudo rules, browser extensions, root certificates) and the output of jobs you dispatch. It does not collect files.
- Is our data separated from other customers?
- On the cloud service, every record belongs to one organisation and is filtered by it in the application and, again, by the database. On a dedicated instance, the server holds only your organisation.
- Can we keep all findings on our own network?
- Yes, with a dedicated instance. It still needs outbound access for licence checks and signed updates.
- Do you support SAML or passkeys?
- Not yet. Single sign-on uses OpenID Connect, and two-factor authentication uses authenticator-app codes.
- Is there an API key for integrations?
- Not yet. Scripts sign in as a user and use a short-lived Bearer token. See API.
- Can Holistra send alerts by email or Slack?
- Not yet. Alerts appear in the dashboard.
- Why do agent services and files still use another name?
- They keep the product's earlier technical name so that existing installations keep working. They will be renamed in a later release.
Getting help
Email [email protected] with what you were doing, the time it happened, and any error message. For agent problems, include the relevant lines from the agent's log; remove enrolment tokens from anything you send.