# Troubleshooting

This page covers solutions to the most common issues administrators encounter after deploying Keeper Endpoint Privilege Manager. If the problem you're seeing isn't covered here, contact Keeper Support and provide the relevant log files from the paths listed in [Reading Logs](/keeperpam/endpoint-privilege-manager/user-guides/reading-logs.md).

## Troubleshooting Topics

[The Agent Service Won't Start](#the-agent-service-wont-start)

[Plugins are Not Loading or Show a Failed Status](#plugins-are-not-loading-or-show-a-failed-status)

[Policy Evaluation is Not Working as Expected](#policy-evaluation-is-not-working-as-expected)

[Agent Registration is Failing](#agent-registration-is-failing)

[The Agent Registered but Policies Aren't Appearing](#the-agent-registered-but-policies-arent-appearing)

[HTTP API Requests are Being Rejected](#http-api-requests-are-being-rejected)

[Verifying the Service is Healthy](#verifying-the-service-is-healthy)

[Where to Find Log Files](#where-to-find-log-files)

***

## The Agent Service Won't Start

**What you'll see:** The service fails to reach a running state, starts and then immediately stops, or errors appear in the system event log.

**Common causes and what to check:**

**Port conflicts.** The agent requires three ports on localhost: `6888` (HTTP), `6889` (HTTPS), and `8675` (internal MQTT broker). If any of these are in use by another process, the service will fail to start.

To check port availability:

powershell

```powershell
# Windows
netstat -an | findstr :6888
netstat -an | findstr :6889
netstat -an | findstr :8675
```

bash

```bash
# Linux / macOS
netstat -an | grep :6888
netstat -an | grep :6889
netstat -an | grep :8675
```

If a port is in use, either stop the conflicting process or reconfigure it to use a different port.

**Malformed configuration.** A JSON syntax error in `appsettings.json` or any plugin or job configuration file will prevent the service from loading. Run the file through any JSON validator and look for missing commas, unmatched brackets, or invalid values.

**Missing .NET runtime.** KEPM requires .NET 8.0 to be installed. Verify it is present:

bash

```bash
dotnet --list-runtimes
```

**File permission issues.** The service account must have read and write access to the installation directory and its storage subdirectory. Verify permissions on:

* Windows: `C:\Program Files\Keeper Security\Endpoint Privilege Management\`
* Linux: `/opt/keeper/sbin/`
* macOS: `/Library/Keeper/sbin/`

## Plugins are Not Loading or Show a Failed Status

**What you'll see:** One or more plugins appear as "Stopped" or "Failed" in the Admin Console, or the service starts but policy evaluation doesn't work.

**Certificate validation failure.** All KEPM plugins must be digitally signed. If a plugin's certificate thumbprint isn't in the trusted list, it won't load. Check the service log for messages containing `Plugin failed security validation`. If you are running a custom or third-party plugin, see [Signed Certificate Support](/keeperpam/endpoint-privilege-manager/reference/signed-certificate-support.md) for how to add the certificate to the trusted list.

**Executable not found.** Verify the plugin executable exists at the path specified in the plugin's JSON configuration file, and that the service account has execute permission on it.

**MQTT connection failure.** Plugins communicate internally over the embedded MQTT broker on port 8675. If the broker failed to start (check the service log), no plugins will be able to connect. The most common cause is port 8675 being in use — see the port conflict steps above.

## Policy Evaluation is Not Working as Expected

**What you'll see:** Actions that should be controlled proceed without prompts, or actions that should be allowed are being denied.

**The KeeperPolicy plugin is not running.** Policy evaluation stops entirely if the KeeperPolicy plugin is not in a running state. Confirm it is running:

bash

```bash
curl -sk https://localhost:6889/api/plugins | \
  python3 -c "import sys,json; p=[x for x in json.load(sys.stdin)['plugins'] if x['name']=='KeeperPolicy'][0]; print(p['status'])"
```

Expected output: `Running`

**The agent is not registered.** Policies are delivered from the Keeper server only after the agent has completed registration. Check registration status:

bash

```bash
curl -sk https://localhost:6889/api/Keeper/registration
```

The response should contain `"IsRegistered": true`. If it doesn't, complete registration using the `KeeperRegistrationHelper` — see the relevant deployment guide for your operating system.

**Policy has not synced yet.** After registration, the first policy sync can take up to a few minutes. Check the timestamp of the `currentPolicies.json` file in the KeeperPolicy plugin directory to confirm policies have been received.

**The policy is in Monitor mode.** Policies in Monitor or Monitor & Notify state log events but do not enforce controls. In the Admin Console, check the policy's Status field and change it to Enforce if you intend it to block or prompt.

## Agent Registration is Failing

**What you'll see:** The registration request returns an error, or the agent remains in an unregistered state after the installer runs.

**Service not fully initialized.** After the service starts, it takes 15–30 seconds for all plugins to load and for the KeeperAPI plugin to be ready to accept registration requests. Wait and retry.

**Wrong or expired deployment token.** The token format is `hostname:deployment-uid:private-key`. If the token is from an expired or deleted deployment package in the Admin Console, registration will be refused. Generate a new deployment package and use the new token.

**No outbound connectivity to Keeper.** Registration requires HTTPS access to the Keeper cloud backend. Verify the machine can reach `keepersecurity.com` on port 443. If you are in an airgapped environment, see the [Airgapped Support](/keeperpam/endpoint-privilege-manager/user-guides/airgapped-support.md) guide.

**Already registered with a different token.** If the agent is already registered and you need to re-register it with a different deployment package, use the `force=true` parameter:

bash

```bash
curl -X POST "https://localhost:6889/api/Keeper/register?token=<token>&force=true" --insecure
```

## The Agent Registered but Policies Aren't Appearing

**What you'll see:** Registration succeeds, but no policy controls appear for end users, or the `currentPolicies.json` file is empty.

First, wait a few minutes — the initial policy sync runs shortly after registration. If policies still don't appear, check:

1. The deployment package used for registration has policies assigned to it in the Admin Console.
2. The machine's collections are correctly configured to include this device.
3. The KeeperPolicy plugin is running (see plugin check above).
4. The service log contains a line similar to `Local policy merge complete: N server + N local = N total policies` — if N is 0, no policies have been received from the server.

## HTTP API Requests are Being Rejected

**What you'll see:** API calls to `https://localhost:6889` return `401 Unauthorized` or `403 Forbidden`.

KEPM uses process-based authentication for its local API. The calling process must either be a KPM-launched process (tracked in the process registry) or a process running with administrator privileges. The following will not work from an unprivileged context:

* Running `curl` from a non-elevated terminal on Windows
* Calling the API from a non-admin user process that wasn't launched by KPM

Use an elevated terminal (`Run as administrator` on Windows, `sudo` on Linux/macOS) to make direct API calls during troubleshooting.

## Verifying the Service is Healthy

Run these checks in sequence to confirm the service is fully operational:

bash

```bash
# 1. Service is responding
curl -sk https://localhost:6889/health
# Expected: {"status": "running"}

# 2. Agent is registered
curl -sk https://localhost:6889/api/Keeper/registration
# Expected: "IsRegistered": true

# 3. Core plugins are running
curl -sk https://localhost:6889/api/plugins
# Expected: KeeperAPI and KeeperPolicy both show "Running"
```

## Where to Find Log Files

Log files are located at:

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="134">Platform</th><th>Path</th></tr></thead><tbody><tr><td>Windows</td><td><code>C:\Program Files\Keeper Security\Endpoint Privilege Management\Plugins\bin\KeeperLogger\Log</code></td></tr><tr><td>Linux</td><td><code>/opt/keeper/sbin/Plugins/bin/KeeperLogger/Log</code></td></tr><tr><td>macOS</td><td><code>/Library/Keeper/sbin/Plugins/bin/KeeperLogger/Log</code></td></tr></tbody></table>

A new log file is created each day. Log files are retained for 15 days before being automatically deleted. For guidance on reading and interpreting log content, see [Reading Logs](/keeperpam/endpoint-privilege-manager/user-guides/reading-logs.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/user-guides/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.