Troubleshoot Workstation Agent

Use these answers when the Workstation Agent doesn't install, start, or appear in Agent Activity in OpenLM Platform as expected. For the installation steps, see Install Workstation Agent.

Where are the agent logs?

Each user's Workstation Agent writes its own logs:

• Windows: %APPDATA%\OpenLM\Agent\logs\, in the profile of the user. The OpenLM Agent Updater Service logs to %ProgramData%\OpenLM\Agent\logs\, in files that start with UPDATER_.
• Linux: /opt/openlmagent/logs/<user>/. When the agent can't start, its messages are in the journal of the user: journalctl --user -u openlmagent.
• macOS: /Library/OpenLMAgent/logs/<user>/.

The agent writes one log a day for everything, Agent.ALL.<yyyymmdd>.log, and one for each area, such as Agent.Agent.<yyyymmdd>.log. Each start begins with Running v<version>. A connected agent then logs SENDING: Agent details: <address>, "Connected" and sends alive messages.

To get more detail, set logging.minimumLevel to Debug in settings.json, and restart the agent, as described in Change the agent settings.

Why does the installer reject the authorization file?

The Windows installer checks the authorization file when you select Next on the Agent Authorization page, and reports a problem in an "Authorization file validation error" message:

• The file is empty. or The file could not be read. It may be corrupted or encrypted with an unknown key.: the file is incomplete or was changed. Download it again from Identity.
• clientType property value must be Agent.: the file belongs to another component, such as a Broker. Generate a file for a client of type Agent.
• cloudLocation property is not valid for cloud mode.: the address in the file isn't an OpenLM Platform in the cloud. Select OpenLM On-Premise on the Operation Mode page for a self-hosted OpenLM Platform.
• cloudLocation property is not valid for on-premise.: the file belongs to an OpenLM Platform in the cloud. Select OpenLM Cloud on the Operation Mode page.
• A message that a property can't be empty, such as clientId property can't be empty.: the file is incomplete. Download it again.

Why does Check connectivity fail?

When you connect the Windows installer to a self-hosted OpenLM Platform, Check connectivity on the Agents Hub Configuration page connects from the machine to the Agents Hub of the host in Host name. If it reports Unable to connect. Please check your OpenLM Agents Hub instance and the address you provided., check these causes:

• The host name: enter the host name only, without https:// or a path.
• The port and SSL: Port and Use SSL must match how your OpenLM Platform accepts connections, 443 with SSL by default.
• The network: the machine needs access to the host on that port. A firewall or proxy can block it.

Why doesn't the agent appear in Agent Activity?

The Agent Activity list doesn't update by itself, so first select the Refresh icon. If the Workstation Agent still isn't listed, check these causes:

• The agent isn't running: on Windows, the agent runs for the signed-in user, as OpenLM.Agent.Windows.Core.exe. On Linux, run systemctl --user status openlmagent as the user. On macOS, run launchctl print "gui/$(id -u)/com.openlm.agent" as the user.
• The agent can't reach OpenLM Platform: the agent log shows Failed reconnecting to Hub with the address the agent tried. Allow outbound HTTPS from the machine to the address of your OpenLM Platform.
• The agent still has the placeholder authorization file: on Linux and macOS, Failed reconnecting to Hub names an address that isn't your OpenLM Platform. Replace the file, as described in Install Workstation Agent on Linux or Install Workstation Agent on macOS.
• A self-hosted OpenLM Platform has no address in settings.json: on Linux and macOS, set agentsHub.address, port, and useSSL, and restart the agent, as described in Install Workstation Agent on Linux or Install Workstation Agent on macOS. A firewall or proxy can also block the connection.
• The authorization client was deleted, or its secret was reset: give the agent a new authorization file, as described in Give the agent a new authorization file.

Why doesn't the Personal Dashboard open?

When a user can't open the Personal Dashboard from the Workstation Agent, check these causes:

• End-User Services is off: on Windows, the installer adds the OpenLM Personal Dashboard shortcut only when you select Use End-User Services in the installer, or set USE_ENDUSERS_SERVICES="true" in a silent installation.
• The installation didn't open it: a silent installation on Windows doesn't open the dashboard, and an installation on Linux opens it only for the users who are signed in to a desktop session. Open it from the agent, as described in Install Workstation Agent on Windows or Install Workstation Agent on Linux.
• The agent can't get the address of the dashboard: to open the dashboard, the agent gets its address from OpenLM Platform. Check that the agent is connected, as described in Why doesn't the agent appear in Agent Activity?

When the agent can't get the address, it logs SignInDashboard: Personal Dashboard address could not be retrieved from AgentsHub (empty response). Skipping dashboard open. The process that opens the dashboard runs next to the agent, so it can write to a second log file of that day in the log folder, such as Agent.ALL.<yyyymmdd>_001.log.

Why doesn't the agent start on macOS?

Reload the LaunchAgent in the user context, not as root:

launchctl bootout "gui/$(id -u)/com.openlm.agent" 2>/dev/null
launchctl bootstrap "gui/$(id -u)" /Library/LaunchAgents/com.openlm.agent.plist

Then confirm that the quarantine attribute is cleared. This command returns nothing when it is:

xattr -p com.apple.quarantine /Library/OpenLMAgent/OpenLM.Agent.macOS

If it is still set, run sudo xattr -rd com.apple.quarantine /Library/OpenLMAgent. Also confirm that you installed the build that matches the processor of the Mac, Intel or Apple Silicon.

Why are window titles empty on macOS, or why does the Screen Recording prompt repeat?

Grant the Screen Recording permission, as described in Grant the required permissions, and restart the agent. A repeating prompt usually means that the recorded permission identity is unstable, which is related to ad-hoc signing. Grant the permission once for each Mac, and don't sign the binary again.

Why isn't Safari history collected on macOS?

Grant Full Disk Access to OpenLM.Agent.macOS, as described in Grant the required permissions, and confirm that webmonitor.useWebMonitor is true in settings.json. Without Full Disk Access, the agent skips Safari history without an error. Other browsers are not affected.

Why does the agent keep restarting on Linux?

On Linux, systemctl --user status openlmagent shows activating (auto-restart) (Result: core-dump), and the Workstation Agent writes no log. Read the reason in the journal:

journalctl --user -u openlmagent -n 50 --no-pager

If the journal shows Couldn't find a valid ICU package installed on the system. Please install libicu (or icu-libs) using your package manager and try again., install the ICU library. On Rocky Linux and Red Hat Enterprise Linux, run sudo dnf install libicu. The agent starts at its next automatic restart, within about 10 seconds.

Why does the agent keep restarting for a new user?

After an installation from the tar.gz archive on Linux, the Workstation Agent of a user you added later can stop at every start, and the journal shows Access to the path '/opt/openlmagent/OpenLM' is denied. The agent stores its data in the .config folder of the user, and writes its log to /opt/openlmagent/logs/<user>. A new account has no .config folder yet, so the agent tries to store its data in /opt/openlmagent, where the user can't write, and the user has no log folder there either.

To fix it, create both folders, and restart the agent of the user:

sudo mkdir -p /opt/openlmagent/logs/<user>
sudo chown <user> /opt/openlmagent/logs/<user>
sudo -u <user> mkdir -p /home/<user>/.config

Then, as the user, run systemctl --user restart openlmagent.

Why does the package installation print warnings about the openlm account?

The Linux packages of the Workstation Agent set the owner of the installed files to an openlm account. Without that account, the DEB package prints chown: invalid user: 'openlm:openlm', and the RPM package prints warning: user openlm does not exist - using root, for each file. The files then belong to root, and the agent works. You can ignore these lines.

Which errors in the log can you ignore?

When the Workstation Agent starts on Linux, it logs Error loading of built-in plugins from: /opt/openlmagent/Extensions, because the extensions exist only on Windows. At the first start of a user, the agent also logs Failed to read Web Sessions Last Report Time, because the file it reads doesn't exist yet. Both are expected.

How do you check that the problem is fixed?

After you fix a problem, check that the agent runs and reports:

1. Restart the agent, as described in Change the agent settings.
2. Open the agent log, and find a line with "Connected".
3. In OpenLM Platform, open Navigation, select Agents, then Agent Activity, and select the Refresh icon.
4. Find the row with the host name of the machine. Online shows a check mark while the agent is connected.

Next step

If the agent still doesn't connect, collect its log with logging.minimumLevel set to Debug, and contact OpenLM support. Once the agent is online, continue the setup with Install the Directory Synchronization Agent (DSA).