--- title: Troubleshoot Workstation Agent description: "Find Workstation Agent logs, and fix rejected authorization files, failed connectivity checks, and agents that restart or don't appear in OpenLM Platform." product: OpenLM Platform --- 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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/index). ## 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//`. When the agent can't start, its messages are in the journal of the user: `journalctl --user -u openlmagent`. - **macOS**: `/Library/OpenLMAgent/logs//`. The agent writes one log a day for everything, `Agent.ALL..log`, and one for each area, such as `Agent.Agent..log`. Each start begins with `Running v`. A connected agent then logs `SENDING: Agent details:
, "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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/manage#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](#where-are-the-agent-logs) 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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/linux#connect-the-agent) or [Install Workstation Agent on macOS](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/macos#connect-the-agent). - **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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/linux#connect-to-a-self-hosted-openlm-platform) or [Install Workstation Agent on macOS](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/macos#connect-the-agent). 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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/manage#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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/windows#open-the-personal-dashboard) or [Install Workstation Agent on Linux](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/linux#open-the-personal-dashboard). - **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?](#why-doesnt-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](#where-are-the-agent-logs), such as `Agent.ALL._001.log`. ## Why doesn't the agent start on macOS? Reload the LaunchAgent in the user context, not as root: ```bash 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: ```bash 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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/macos#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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/macos#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: ```bash 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/`. 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: ```bash sudo mkdir -p /opt/openlmagent/logs/ sudo chown /opt/openlmagent/logs/ sudo -u mkdir -p /home//.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](https://www.openlm.com/documentation/cloud/getting-started/install-workstation-agent/manage#change-the-agent-settings). 2. Open the [agent log](#where-are-the-agent-logs), 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. :::info[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)](https://www.openlm.com/documentation/cloud/getting-started/install-dsa). :::