Troubleshooting Platform Agent

This feature is currently available only to customers participating in a Private Preview. If you'd like to participate and be among the first to try this feature, ask our support or account team for details.

This page provides help for issues and questions you might encounter while using Delinea Platform Agent.

This page gives information relevant to the Platform Agent. For information about the other type of agent, Privilege Control Agent, see Privilege Control Agent.

When escalating to Delinea support, include:

  • Agent version (visible in the Platform UI at Settings > Connection points > Agents)

  • Operating system and build (Use the commands uname -a on Linux, winver on Windows)

  • Tenant URL (*.delinea.app)

  • Agent logs (See Collecting Debugging Information)

  • Install log (if the issue is related to installation, see Files and Directories on Platform Agent)

  • The cumulative installation precheck exit code, if applicable

Review all of the information for sensitive content before sharing with Delinea Support.

Collecting Debugging Information

To collect debug info for the Delinea support team to investigate an issue:

  1. Turn on debugging. See Increasing the Log File Detail Level.

  2. Reproduce the issue.

  3. Download the logs.

    • From the Platform (recommended):

      1. Navigate to Settings > Connection points > Agents

      2. Select your agent

      3. Click Logs

      4. Click Download Logs

    • From the Endpoint

      For Windows, zip the following:

      • C:\ProgramData\Delinea Engine\log\*

      • C:\ProgramData\Delinea Engine\data\settings\*

      For Linux:

      • Bundle the following:

        • /var/delinea-engine/log/

        • var/log/delinea-agent-install.log

        • /var/delinea-engine/data/settings/

  4. Provide the zip / archive file to the Delinea support team through your support case.

Increasing the Log File Detail Level

The default setting for Platform Agent logs includes critical errors only, without much detail. When you need detailed information, increase the verbosity of the default logging level to Debug. This must be done directly on the endpoint. A future Platform Agent enhancement to adjust the log level remotely from the platform is planned.

Windows

Location:

C:\Program Files\Delinea Engine\cur\appsettings.json

  • C:\Program Files\Delinea Engine\cur\appsettings.json

    Registration, heartbeat, key rotation, upgrade, communication

  • C:\ProgramData\Delinea Engine\data\runtime\delinea\{workload}\{version}\appsettings.json

    A specific workload (login, privilege elevation, policy)

Steps:

  1. In the file appsettings.json, observe “Logging.”

  2. Replace values in this section with one of the following values (in order from most to least verbose): Trace, Debug, Information, Warning, Error, Critical.

  3. Save the file.

  4. Restart the Platform Agent engine service so the workload re-reads the config.

Linux

On Linux, each workload has its own debugging CLI:

Workload Name Path
Platform Agent Core (Broker and Policy Evaluation) /opt/delinea/login/bin/dpadebug
Platform Agent Login /opt/delinea/pe/bin/dpadebug
Platform Agent Elevation /opt/delinea/agentcore/bin/dpadebug

These CLIs all have a shared set of options:

Option Function
-o|--on Enable debug log
-f|--off Disable debug log
-s|--status Print current log levels
--set <LOG_LEVEL> Set the log level to one of: trace, debug, info, warn/warning, error, fatal
-v|--version Display the version information
--verbose Enable verbose (debug) logging
-?|-h|--help Show help information

Example: Run with parameter --on to turn on debug log. Run with parameter --set <LOG_LEVEL> to set a specific log level.

Can't Find Log Files

Before you can begin troubleshooting, you need to know where to find the Delinea Platform log files. See Files and Directories on Platform Agent.

Viewing Agent Status

See Agent Status in the Platform UI. See Verifying Platform Agent Status From the Platform in Managing Agents (Platform Agent).

Common Issues

Agent Doesn't Appear in the Platform UI After Installation

Symptoms: The install completes successfully but the agent never shows up in Settings > Connection points > Agents.

Common causes:

  • Network blocked on port 443. Fix firewall or proxy rules.

  • Tenant feature flags not enabled. Contact your Delinea representative or Customer Success.

  • Registration code expired. Generate a new code from Settings > Agents.

Diagnostic steps:

  1. Check the install log.

    Linux: tail /var/log/delinea-agent-install.log

    Windows: review Event Viewer entries from the install timestamp

  2. Check the service is running.

    Linux: systemctl status delinea-engine

    Windows: Service Manager > Delinea.Engine should be Running

  3. Check the agent state files.

    Look in the data\settings\ directory for device-code.config (registration code), registration.config (created on successful registration), and tenant.config (tenant identifier).

    If registration.config is missing or empty, the agent did not complete registration.

  4. Check network connectivity.

    From the agent host, verify port 443 outbound to your platform tenant works.

    On Linux, you can re-run sudo ./install.sh --diagnose from the original install bundle to revalidate.

  5. Check the registration retry logs.

    The agent retries registration up to 5 times with exponential backoff. Look for "Error during Engine Management registration" in the runtime logs after all retries are exhausted.

Agent Goes Offline Intermittently

Symptoms: The agent registers successfully and appears online, but periodically disconnects and reconnects.

Diagnostic steps:

  1. Look for connection errors in the runtime logs (MQTT broker reachability, TLS errors, WebSocket upgrade failures).

  2. Check whether your network has TLS-inspecting proxies that might break the agent's mutual TLS connection.

  3. Verify the regional platform endpoints are reachable. See Platform Engine URLs in Engine Management.

  4. Check for resource pressure on the host (high CPU, memory exhaustion, or disk full).

Policy doesn't apply or is not enforced

Symptoms: A user attempts to log in or elevate privileges, but expected policy behavior (MFA prompt, deny rule, etc.) does not occur. Or a policy was changed and old behavior persists.

Diagnostic steps:

  1. Wait for cache propagation. Policy changes usually propagate within seconds, but can take up to approximately 5 minutes to reach agents.

  2. Verify policy targeting. Confirm the policy targets the correct endpoint and user.

  3. Verify policy is deployed. Confirm on the computer object in inventory that the policy is present and deployment status is Active.

    Deployment status is indicative of platform-side deployment, but not necessarily what is present on the endpoint. If Deployment status is Active but the endpoint is still not applying the policy after 5 minutes, you should contact Delinea Support. See Collecting Debugging Information.

  4. (Linux-only) Endpoint-based privilege elevation check:

    Run sudo -l to see which privileged commands you are entitled to execute.

MFA Challenge Fails or Hangs

Symptoms: The MFA prompt appears during login but never completes or fails with a non-actionable error.

Diagnostic steps:

  1. Confirm the Authentication Profile referenced by the policy is correctly configured on the tenant.

  2. The user may need to retry, or the admin may need to verify MFA integration health.

  3. Microsoft Entra MFA: verify number-matching (Microsoft Authenticator) is enabled in the Authentication Profile if your policy requires it. Number-matching MFA falls back to Device Code Flow when direct MFA is unavailable.

  4. Check your Delinea Platform logs:

    • Insights > Audit Logs > Search for “Identity”

    • Settings > MFA and security > MFA Providers > Select your MFA provider > Audit tab (is only present for some integrations)

    • Settings > Connection points > Agents > Select your endpoint > Logs > Select your workload which MFA is failing for (Platform Agent Login or Platform Agent Privilege Elevation)

MFA Pass-Through Not Working

First, check the agent and workload status. See Verifying Platform Agent status.

If the agent is online and the expected workloads are active, contact DelineaSupport. See Collecting Debugging Information.

Granular Privilege Elevation Not Working on *nix

On Linux systems, when the directory /var is NFS mounted, Platform Agent may not work properly.

Resolution:

Do not mount /var on NFS.

Windows agent is present in Inventory after uninstallation

After uninstalling the Platform Agent, a stale record for a Windows machine may still be visible in inventory. If this stale record persists for more than 5 minutes, Delinea recommends deleting the agent from the Settings > Connection points > Agents screen, which will also remove the agent from Inventory.

Can't Find User for Subjects

Symptoms: When searching for a known user to add as a subject for a policy, the user's name does not appear, or no user names appear.

Diagnostic steps:

For AD-based users:

  1. Open the Delinea Connector Configuration UI.

  2. On the Status tab, look at the Last connection result.

    • If the message is "Connector is not available," select the Connector tab and click Start.

    • If the message is "Successful" but the last connection time was a long time ago, select the Connector tab and click Stop.

      When the connector stops, click Start. It might take several seconds for the connector to stop and start.

  3. If your known user or all users are still not showing up in your search to a policy target, check the Connector logs. Contact Delinea support if necessary.

For federated / external identity provider users:

  1. Confirm the user is provisioned to the Delinea Platform, not just present in the identity provider. A federated user is typically only searchable after they've signed in at least once (just-in-time provisioning) or an integration has synced them. For example, a user who exists in Okta but has never logged in to the Delinea Platform won't appear.

  2. Check the federation/provisioning configuration. Verify the identity provider connection is healthy and, if you rely on automatic provisioning, that the sync is enabled and has run recently. Re-run or wait for the next sync cycle if needed.

  3. Verify search attribute mapping. Confirm the attribute you're searching on (email, UPN, display name) is actually mapped and populated from the identity provider. A missing mapped attribute means no match.

  4. For all non-AD users: if the user is confirmed present and active but still doesn't appear in the policy subject search, check whether the issue is search/indexing-wide (no users appear) versus user-specific (one user missing). The first points at a Platform-side search/service problem; the second at that account's provisioning state. Contact Delinea support if it persists.

  5. Familiarize yourself with the Identity Providers documentation.

Inactive Policy Still Seems Active

Symptoms: A Login or Privilege Elevation policy status is Inactive, but you can still perform login or privilege elevation on the machine.

Cause: Policy changes usually propagate within seconds but can take up to approximately 5 minutes to reach agents. A policy may still be cached on the endpoint.

Diagnostic steps:

If an inactive policy is still in effect after 5 minutes, contact Delinea support.

Machine Not In Target List

Symptoms: When setting up a policy, the Targets section is not showing the desired machine.

Diagnostic steps:

  1. The targets you can select come from Inventory. If you are looking for a machine and it is not showing in the Targets list, check to see whether that same machine appears in the Inventory list.

  2. Ensure the agent installed successfully. See Task 3: Install the Platform Agent.

  3. If a machine is not listed under Targets, and it is also not listed under Inventory, the self-discovery of the agent may have failed. Contact Delinea support.

  4. If a machine is not listed under Targets, but it is listed under Inventory, contact Delinea support.