Skip to content

Documentation

Troubleshooting

Find your symptom below and work through the checks in order: the most likely cause comes first. Each check says exactly where to look in the console.

Before you start

  • Most checks need an administrator account (the Audit and Settings pages, the Terminal tab and debug logs are for administrators only).
  • Words such as verdict, check-in and enrollment are explained in the glossary.
  • If the AI assistant is turned on, you can also ask it, for example "why does host web-01 fail rule SSH Root Login Disabled?". It reads the same data you see.

Sign-in problems

  1. "You do not have access to LEA Platform yet." Your identity was accepted but matches no role. An administrator opens Settings → Single sign-on and either approves your request under Access requests (Approve), or adds a role mapping for your group or app role on the provider. Then sign in again.
  2. "Your session ended. Sign in again." Sessions end after a period of inactivity, after a maximum session length, or when your identity provider no longer confirms you (account disabled, role removed). Sign in again. If it happens every few minutes, an administrator checks Sessions and runs Run test on the provider in Settings → Single sign-on.
  3. "The identity provider refused the sign-in", "could not be verified" or "Single sign-on is not configured correctly" (the address may show error=provider_error or error=invalid_token). An administrator opens the provider in Settings → Single sign-on and clicks Run test. The most common causes are an expired client secret, a redirect address that does not match exactly, or the wrong tenant. All codes: Error codes.
  4. "The identity provider cannot be reached right now." The LEA server cannot reach your identity provider. Check the network between them (DNS, firewall, proxy).
  5. "Your identity provider sent too many groups." (Microsoft Entra ID) Your account is in more than 200 groups. The administrator maps Entra app roles instead of groups.
  6. Wrong password several times. After 5 failed attempts a local account is locked for 15 minutes. Wait, then try again.
  7. Single sign-on is down and nobody can sign in. Use a break-glass account. On the LEA server, run the command below, then choose Sign in with a local account on the sign-in page.
./lea_ha.sh breakglass on admin

Replace admin with the user name of your break-glass account (a local user from Settings → Local users). Run it from the LEA Platform installation directory. The window closes by itself; close it early with ./lea_ha.sh breakglass off admin.

Warning: Opening a break-glass window raises a critical notification for every administrator. Close it as soon as single sign-on works again.

A script or tool is refused by the API

  • 401 with password_disabled: password tokens are off while single sign-on is on. Use a personal access token, an API account or an application token. See Create a personal access token.
  • 403 with not_allowed: the API account's Allowed endpoints do not include that method and path. An administrator adds it in Settings → Local users.

More detail: Signing in and Sign-in reference.

A host is missing or not reporting

The host does not appear at all

  1. The agent never enrolled. On the host, check that the agent service is running. On Linux installed with the standard script:

    systemctl status lea
    journalctl -u lea --since "1 hour ago"
    

    If the journal shows Permission denied and status=203/EXEC for /var/lib/lea/lea-agent-linux-…, the host has SELinux enforcing: label the agent as described in Hosts with SELinux enforcing.

  2. The deployment token is wrong, used up or expired. Open Settings → Deployment tokens and check the token's uses and expiry. Create a new token if needed and put it in the agent configuration (LEA_ENROLL_TOKEN in lea.conf; on Linux with the standard script the file is /var/lib/lea/lea.conf). Then restart the agent (systemctl restart lea).

  3. The host cannot reach the LEA server. From the host, check DNS, firewall and proxy to the LEA address on port 443.

  4. You are filtering it out. On Compliance, click Clear all in the filter bar and search for the host name.

The host is listed but its data is old

  1. Check when it last checked in. Open the host page → Terminal tab. The strip at the top says REACHABLE, LATE, STALE or NEVER SEEN and when the last check-in was.
  2. Check the enrollment state. On Compliance, look at the Enrollment column (hover over it to see the last rejection reason), or open the host page → Overview → Enrollment.
    • Certificate error: often fixes itself within minutes. If not, click Re-enroll on the host's Overview, choose a window and click Open Window. After the next check-in the host is in Probation: check it is the right machine, then Confirm.
    • Never connected: the certificate was issued but never used. Check the agent is running and can reach the server.
    • Re-enrollment conflict: two machines claim the same identity (for example a cloned virtual machine). Investigate before you confirm.
    • Full list of states: Agent enrollment.
  3. The agent is stopped or the machine is off. On the host: systemctl status lea.
  4. The host clock is wrong. Certificates need a correct time. Check the host's time and time synchronisation.
  5. Look at the agent's own messages. Host page → Agent logs, filter Errors and Warnings.

The host is listed as INACTIVE

Inactive hosts are not evaluated. A host is activated automatically only when its deployment token has Activate enrolled agents automatically switched on. Otherwise an administrator activates it, for example by asking the AI assistant "activate host web-01" and approving the change, or with the LEA CLI:

lea api -X PATCH 'clients?id=eq.42' -d '{"active": true}'

Replace 42 with the host's number, shown in the host page address (/hosts/42).

A rule shows FAIL but the host is fine

  1. Read the result first. Open the result (click the FAIL pill on the host's Rule results tab, or on Execution). Compare Last check (stdout, stderr) with the failed expectation. See How to read a result.
  2. The output says "Permission denied" or is empty. The LEA agent runs as an unprivileged user (lea on Linux) and cannot read the file. Give that user read access to the file. Do not add sudo to the rule's command.
  3. The setting is in another file. Many services read extra files (for example /etc/ssh/sshd_config.d/). The rule may only read the main file. Check the Commands under What is checked on the result page.
  4. The value matches a commented-out line, or the format differs (extra spaces, upper/lower case). The expectation is a Python regular expression: POSIX classes such as [[:space:]] do not work, and in rule JSON every backslash is doubled (\\b). An administrator can test it against the real output with the Regex Builder in the rule editor (Expectations section).
  5. The rule is for another distribution. Check the host's distribution on the host page → Overview and the rule's Definition tab. Commands may differ per distribution.
  6. You fixed the host recently. The result changes only on the rule's next run (its interval, one hour by default). To confirm your fix now, run the rule's command in the host's Terminal tab (administrators) and compare the output.
  7. The rule itself is wrong for your site. Change the rule (or its parameters) instead of the host. See Rules.

A rule shows PASS but the host is not fine

  1. The rule only has a "must not match" expectation and the output is empty. Nothing forbidden was found because nothing was read. Add a "must match" expectation of \S (the output is not empty), and check stderr for "Permission denied".
  2. The pattern matches a commented-out line. PermitRootLogin no also matches #PermitRootLogin no. Anchor the pattern to the start of a line: (?m)^[ \t]*PermitRootLogin[ \t]+no\b.
  3. The service is not installed and the rule accepts LEA_RULE_no_service. That is intentional: a setting of a service that is not there cannot be wrong. See Read raw output against the expectation.

To change a rule, see Write and edit rules.

A rule shows INFO or NO RESULTS

  1. The rule has not run yet. A new rule, or a host just added to a group, gets a result after the next run of the rule (up to one rule interval).
  2. The host is not assigned the rule. Open the host page → Groups tab. The host must be in at least one active group that has the rule. On the result page, the message "This rule is not currently assigned to the host through any active group" confirms it.
  3. The host, rule or group is inactive. Look for an INACTIVE badge on the host page, rule page or group page.
  4. The group assigns nothing. On Groups, click Missing hosts or rules in the summary row.
  5. The rule has no commands for this system. The rule's Definition tab shows which system and distribution each command is for. A Linux-only rule gives no result on Windows.
  6. The host is stale. See A host is missing or not reporting.
  7. The host is in Probation and the rule uses secret parameters. Those rules are withheld until an administrator confirms the host (host page → Overview → Re-enroll dialog → Confirm).
  8. The rule has no expectations. That is an informational rule: it is always INFO. It collects data only and has no verdict. Nothing is wrong.

Remediation did not fix the host

  1. Check that remediation is on for this rule. Rule page → Definition → Remedies. "None defined." means the rule has no active remedy. Library rules keep their fix switched off. See Remediation.
  2. Read the remedy's output. Result page → Latest result → Last remedy: REMEDIATED or REMEDY FAILED, with remedy stdout and stderr. On Run history, filter Remedies to see every attempt.
  3. The remedy needs rights the agent does not have. "Permission denied" or "Operation not permitted" in the remedy output means the agent's user cannot make that change.
  4. The remedy is waiting. Pending remedy on the result page shows a queued remedy. It runs at the host's next check-in. If a function is set to run the remedy, the remedy waits for the function; see Functions troubleshooting.
  5. The remedy worked but the host fails again. Something on the host (configuration management, another administrator) changes the setting back. Look at the result's status changes under Track record.
  6. The remedy runs but the rule still fails. The remedy finished, but the output of the next check still does not meet the expectations. Compare the remedy's output and the next check's output with the expectation.

To see how remedies do across the fleet, add the Remediation widget to a dashboard: it shows the remedy success rate, function errors and which rules have a remedy.

Warning: Remedies run automatically on every failing host that has the rule. Test a remedy on a small test group before you assign the rule more widely.

Rule updates and packs

  1. Import fails with "unknown key". The pack is signed with a key that is not set on the source. Check the source's public key in Settings → Rule sources, or choose the right Source when importing.
  2. Import fails with "bad signature" or "tampered content". The file was changed or damaged after signing (for example an incomplete copy). Copy the .tgz and its .sig file again and compare their sizes with the originals.
  3. Import worked but nothing changed on hosts. That is by design: importing only stages new versions. Open Rules → Updates to review and apply them.
  4. A rule shows under Conflicts. Your site changed the rule and the pack changed it too. Open the diff, then choose to take the new version or keep yours.
  5. Some hosts still run the old version. The change was rolled out with New hosts only. Open the rule page → Versions, or the host page → Held rules, and click Update (one host) or Update all.
  6. A rule is marked retired. The pack no longer ships it. LEA never deletes it; decide yourself whether to keep or deactivate it.

See Rule updates and Packs.

Notifications not arriving

In the console (bell, pop-ups)

  1. Notifications are paused. Open the bell. If a pause is active, click Resume.
  2. You muted them. Account menu → Account settings → Muted. Remove the mute.
  3. Your profile or quiet hours hide them. Account menu → Account settings → Notifications: check which categories reach the bell, pop-ups and desktop, and your quiet hours.
  4. An administrator switched the type off for everyone. Settings → Notifications.

By email, Slack or Teams

  1. Look at the delivery log. Settings → Email, Slack & Teams → Delivery log shows every message and its status (SENT, QUEUED, RETRYING, FAILED, SKIPPED) with the error. The connection card shows FAILING with the last error.
  2. You have not connected your address. Account menu → Account settings → Email, Slack & Teams: connect your email (or Slack/Teams) and choose which categories go there.
  3. Mail server errors. "535" or "sign-in rejected" means a wrong user or password for the mail server. "Certificate not trusted" means an internal mail relay with your own certificate authority: paste the CA certificate in the connection's advanced settings.
  4. Slack and Teams need the internet. On a site without internet, use email through an internal mail relay, or webhooks.
  5. Messages have no links, Slack buttons or /lea do nothing, the Teams bot is silent. Set Public URL of LEA Platform on the Options tab. Slack and Teams must reach that address from the internet (directly or through your reverse proxy).
  6. A user gets nothing. The user must connect the channel under Account settings → Email, Slack & Teams, have a severity set for that category and channel under Notifications → Delivery, and not be muted or in quiet hours (held messages arrive afterwards). Users who have not signed in for longer than Stop for users inactive for (90 days by default) get no messages. An administrator may also have stopped delivery for them on the Recipients tab.
  7. Too many messages. Raise the minimum severity of team routes, mute noisy hosts or rules, or lower Group into one message from on the Options tab.

Error messages in the delivery log, and what they mean:

ErrorFix
SMTP "535" or sign-in rejectedWrong user or password. Gmail needs an app password or OAuth. Exchange Online often has SMTP AUTH turned off: enable it for the mailbox, or use OAuth 2.0 or the Microsoft 365 (Graph API) provider.
Certificate not trustedAn internal relay or a TLS-inspecting proxy. Paste its CA certificate (PEM) in the connection's advanced settings.
Microsoft Graph 403Grant the app the Mail.Send application permission with admin consent, and include the mailbox in any application access policy.
Google unauthorized_clientDomain-wide delegation is missing the scope: https://www.googleapis.com/auth/gmail.send for the Gmail API, https://mail.google.com/ for SMTP with OAuth.
Slack not_in_channel or channel_not_foundInvite the LEA app to the channel (/invite and the app name). Private channels only appear after that.
Slack invalid_auth or no_serviceThe app was uninstalled or the webhook removed. Reinstall it and paste the new token or webhook.
Teams webhook 404 (or 401, 403, 410)The workflow was deleted, turned off or its address changed. Create a new "Post to a channel when a webhook request is received" workflow.
Teams bot 401 on incoming messagesThe app ID or tenant does not match the Azure Bot, or the bot's messaging endpoint points elsewhere.
Teams bot 403 when sendingThe app was removed from that team or chat.

Fix the cause, then retry failed messages from the Delivery log.

Webhooks

  1. Open Settings → Webhooks, tab Log: every delivery is listed with its requests, answers and errors.
  2. Check the address and the secrets of the webhook, then use Test → Dry run and Send once.

See Webhooks → If something goes wrong.

The console is slow or shows errors

  1. Reload the data. Click Updated X ago in the page header. If that does not help, reload the browser page.
  2. The page does not update by itself. Check that the header says Live, not Paused. Click it to switch Auto refresh on.
  3. Check the cluster. Open Settings → Cluster; a yellow or red dot next to Cluster means the cluster is degraded or critical. See High availability.
  4. A page is empty or a button is missing. You may have the read-only role, or a filter is active. Click Clear all in the filter bar. See roles.
  5. You are sent back to the sign-in page. Your session ended. See Sign-in problems.
  6. Large tables are slow. Narrow the view with filters (a group, a severity, a status) instead of scrolling through every row. Results and logs are kept as long as Settings → Data retention says; very long retention means more data to search.
  7. A full-page error with a number (403, 404, 500, 502, 503, 504). The server answered instead of the console: 404 the address is wrong, use Go to LEA Platform; 403 the page is limited to another network; 500, 502, 503 or 504 LEA Platform is starting, restarting or being upgraded, click Try again after a minute. If it stays, send the error number and the time to lea.support@gsr-it.com.

License warnings

A coloured badge in the top bar shows license problems. Click it to open Settings → License.

BadgeWhat it meansWhat to do
Evaluation licenseYou run on a time-limited evaluation license.Request and install a full license before it ends.
Grace periodThe license has expired. LEA Platform keeps working for the number of days shown.Install a renewed license now.
License expiredThe grace period is over.Install a valid license.
No license installed / No license foundNo valid license is installed.Install a license.

To renew on a site without internet:

  1. Open Settings → License.
  2. Under Request License, click Download Request. You should see: a license request file is downloaded.
  3. Send that file to your LEA Platform supplier by your usual offline channel.
  4. When you receive the license file, click Upload License and choose it. You should see: the license details and the top bar badge disappears.

AI assistant problems

  1. "AI assistant is not configured": an administrator sets the provider, model and key in Settings → AI Assistant.
  2. Provider errors (401, model not found, rate limit) come from the configured AI provider, not from LEA Platform. Check the API key, the model name and the Base URL.
  3. An MCP client gets 401: send Authorization: Bearer lea_pat_... with a token that is valid, not expired and not revoked. 403 "The LEA MCP server is disabled": turn on MCP server enabled in Settings → AI Assistant.

More in AI assistant.

Functions

For functions that do not run, fail, time out or do not deliver a remedy, see Functions troubleshooting. First places to look: Settings → Functions (status and recent runs) and the rule editor → Functions section.

Collect this before asking for help

If you still need help, collect this first. It answers most questions before they are asked.

  1. Versions. The bottom of the left sidebar shows API and Console versions.
  2. The exact symptom and time. What you did, what you expected, what happened, and when (with time zone). A screenshot from your own machine helps.
  3. The link. Right-click the host, rule or result → Copy link. Filters are part of page addresses, so copying the browser address also captures the exact view.
  4. The result output. On the result page, copy Last check (stdout and stderr, with the copy button) and, if relevant, Last remedy.
  5. Agent logs with debug. Host page → Agent logs → Capture debug logs → For 15 minutes. Reproduce the problem, then filter Debug and copy the messages.
  6. The host's state. Host page → Overview: enrollment state, certificate, last rejection reason, agent version, distribution.
  7. Audit entries. Audit → Configuration changes: the changes made around the time the problem started.
  8. Cluster and settings state. Settings → Overview and, if you run more than one node, Settings → Cluster.