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.

Troubleshooting Topics

The Agent Service Won't Start

Plugins are Not Loading or Show a Failed Status

Policy Evaluation is Not Working as Expected

Agent Registration is Failing

The Agent Registered but Policies Aren't Appearing

HTTP API Requests are Being Rejected

Verifying the Service is Healthy

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

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

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

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 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

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

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 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

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

# 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:

Platform

Path

Windows	C:\Program Files\Keeper Security\Endpoint Privilege Management\Plugins\bin\KeeperLogger\Log
Linux	/opt/keeper/sbin/Plugins/bin/KeeperLogger/Log
macOS	/Library/Keeper/sbin/Plugins/bin/KeeperLogger/Log

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.