Skip to main content
ComponentsEngineJS ProfilerMobile AppRPA Bot RecorderRUM WindowsAgent
Availability2026.2

Initial checks

Quick checks before deep dives

Log Directory

Find the log folder

No Log File Is Created

Fix log write permissions

A Monitoring Rule Does Not Appear

Locate missing rules

​
Overview

Use this guide to diagnose installation, startup, configuration, Windows UI monitoring, data-upload, and .NET Profiler issues affecting the GermainUX Agent.

​
Initial checks

For most problems, start by confirming:
  • The Agent is running with administrator privileges.
  • The correct monitoring rule is applied.
  • The target application has been restarted since the configuration changed.
  • The GermainUX server is reachable.
  • Logging is enabled for the affected component.

​
Component Logs

The GermainUX Agent, Windows UI worker, and .NET Code Profiler use independent log levels. Supported levels are:
The Agent health and status log is enabled at INFO by default. Windows UI worker and CLR Profiler logging are disabled by default because each monitored process can generate a separate log. Enable DEBUG or TRACE only while investigating a problem. Return the setting to its previous value after troubleshooting to avoid unnecessary disk usage. For Registry configuration details, see GermainUX Agent Settings.

​
Log Directory

All components write to the directory defined by the machine-wide LogPath Registry value. Default:
Because %LOCALAPPDATA% is user-specific, the actual directory depends on the Windows account running each process. Logs use rotation with:

​
Log Files

Some Agent versions or internal diagnostic messages may refer to these components by their earlier or internal names:

​
Apply Logging Changes

Registry settings are read when a component starts. After changing a log level:
  • Restart GermainUXAgent.exe to apply AgentLogLevel.
  • Restart the target application to create a new Windows UI worker and apply WorkerLogLevel.
  • Restart the target .NET application to reattach the profiler and apply CLRLogLevel.

​
No Log File Is Created

If a component is configured with a log level other than OFF, but no corresponding file appears, verify that its process identity can write to LogPath. Logging failures are designed not to crash the component. Therefore, a missing log file can indicate that:
  • The directory does not exist.
  • The directory is not writable.
  • The target application uses a different Windows account from the Agent.
  • Endpoint security software is blocking file creation.
  • The component did not start or attach successfully.
The elevated Agent may be able to write to the directory while the target application cannot. Check permissions using the identity of the monitored application, not only the Agent account.

​
“GermainUX Agent Must Be Run as Administrator”

The Agent requires elevated privileges to detect processes starting and stopping on the computer. It checks its privileges during startup and exits if it is not elevated.

​
When Starting the Agent Manually

Right-click GermainUXAgent.exe and select: Run as administrator

​
When the Error Occurs After Login

The 64-bit installer creates a scheduled task that starts the Agent when a user logs in and requests the highest privileges available to that user. If the logged-in user is a local administrator, the Agent starts elevated without displaying a UAC prompt. If the user is not a local administrator, the scheduled task cannot provide the required elevation and the Agent exits. Make sure the Windows account that remains logged in on the monitored computer is a local administrator. For details, see GermainUX Agent Installation.

​
No Data Appears in GermainUX

Complete the following checks in order.

​
1 1. Confirm That the Agent Is Running

Verify that:
  • The GermainUX Agent icon appears in the Windows system tray.
  • GermainUXAgent.exe is running.
  • germain-agent.log contains a successful startup message.
  • The process is running with elevated privileges.
If the Agent is not running, review its scheduled task and confirm that the logged-in account is a local administrator.

​
2. Confirm the GermainUX Server URL

Check the following Registry value:
It must contain the correct base URL of the GermainUX server. When using a 32-bit Registry tool on 64-bit Windows, the value may appear through the redirected view under:
Confirm that:
  • The URL is present.
  • It uses the correct protocol, normally https://.
  • It references the correct GermainUX environment.
  • It does not contain an unintended path or typographical error.
Restart the Agent after changing the URL.

​
3. Check the Environment Filter

Review the Environment Registry value. If it contains an environment name such as:
the Agent accepts only monitoring rules assigned to that environment. A rule assigned to prod would not be applied. Leave Environment empty to accept monitoring rules from every environment.

​
4. Confirm That Monitoring Is Enabled

Right-click the Agent tray icon and verify that Monitoring Enabled is selected. If monitoring was paused, the Agent can continue running without collecting data.

​
5. Refresh the Configuration

Right-click the tray icon and select Refresh Config. This forces the Agent to retrieve the latest rules instead of waiting for the next PollInterval. Review germain-agent.log for errors if the refresh fails.

​
6. Confirm That a Rule Matches the Application

Open the tray icon’s Configurations submenu. Verify that the target application appears and that:
  • The executable name is correct.
  • The rule is enabled.
  • Windows UI monitoring is enabled when required.
  • CLR attachment is enabled for .NET diagnostics.
  • The rule belongs to the correct environment.
  • The displayed configuration is the expected local or server-provided rule.
If the application is absent:
  • Confirm that a server-provided rule targets its exact executable name.
  • For a local rule, verify the Registry subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets\{executableName.exe}
  • Confirm that the executable name includes .exe.
  • Confirm that ConfigFile contains a valid absolute path.
  • Confirm that Enabled is set to 1.
A local rule takes priority over a server-provided rule for the same executable.

​
7. Restart the Target Application

The Agent normally starts a new Windows UI worker and attaches the CLR Profiler when it detects a new target process. After changing a rule:
1

Close the target application completely

2

Confirm that its process has exited

3

Start the application again

4

Check whether a Windows UI worker starts

5

Review the applicable worker or profiler log

​
8. Check Server and Network Connectivity

Confirm that the monitored computer can reach the configured GermainUX URL. Check for:
  • Firewall restrictions
  • Proxy requirements
  • DNS failures
  • TLS or certificate problems
  • Authentication failures
  • Blocked outbound HTTPS
  • Network security products terminating the connection
Configuration-polling failures normally appear in germain-agent.log. Data-upload failures appear in the relevant:
  • Windows UI worker log
  • CLR Profiler log

​
9. Check queue.outputPath

Inspect the resolved rule JSON from the Configurations submenu. If queue.outputPath contains a file path, facts are written to that local file instead of being sent to GermainUX. For normal server delivery, leave it empty:

​
10. Review Privacy and Exclusion Rules

If only certain values or facts are missing, inspect:
  • maskAll
  • exclusions
  • Feature-level inclusion and exclusion patterns
  • HTTP request and response body exclusions
  • Control selectors
The data may be intentionally masked, anonymized, excluded, or unmatched rather than failing to upload.

​
A Monitoring Rule Does Not Appear

If the expected rule is missing from Configurations:
1

Select Refresh Config

2

Review germain-agent.log for server-polling errors

3

Verify the Agent’s Environment value

4

Confirm that the server-side rule targets the exact executable filename

5

For a local rule, confirm the Targets\{executableName.exe} Registry key

6

Confirm that the JSON configuration file exists and is readable

7

Validate the JSON syntax

8

Restart the Agent

For the rule schema, see Monitoring Configuration Reference.

​
Windows UI Monitoring or Replay Does Not Start

If application-level information is present but Windows UI interactions or replay are missing:
  1. Confirm that the rule enables the Windows UI worker.
  2. For a local rule, verify: UiaWorkerEnabled = 1
  3. Confirm that features.monitor.enabled is true.
  4. Confirm that the required subfeature is enabled, such as:
    • userClicks
    • userSearches
    • clickMaps
    • mouseMaps
    • userFacingErrors
    • replay
  5. Restart the target application.
  6. Enable WorkerLogLevel at DEBUG.
  7. Review the target’s germain-uia-worker-{ruleName-}{pid}.log.
  8. Confirm that GermainUXRumWindows.exe remains in the same installation directory as GermainUXAgent.exe.

​
Interactions Are Missing but Replay Works

If only specific clicks or searches are missing:
  • Check the UI Automation control type.
  • Confirm the control’s AutomationId.
  • Confirm its visible label.
  • Confirm its Win32 class name.
  • Review configured regular expressions.
  • Verify whether a selector requires a double-click.
  • Confirm that all specified filter fields match; filter conditions use AND logic.
The application may expose different UI Automation information than expected.

​
Replay Is Incomplete or Drifts from the UI

If replay does not accurately reflect the application:
1

Confirm that the required replay events are enabled

2

Review thumbnail rules

3

Review color-sampling configuration

4

Temporarily enable the relevant debug options while working with Germain Software Support

5

Consider selfHealEnabled only when actual replay drift has been confirmed

Detailed UI diagnostics can create substantial log volume. Disable them after the investigation.

​
Installer Reports a Missing Redistributable

The MSI installer requires Microsoft Visual C++ 2015–2022 Redistributable. Install the package matching the installer architecture: Then run the GermainUX installer again. The MSI checks for this prerequisite but does not install it automatically.

​
.NET Profiler Does Not Attach

If .NET metrics, exceptions, garbage-collection facts, or CPU samples are missing, verify the following.

​
Confirm CLR Attachment Is Enabled

For a local rule, verify:
In the resolved configuration, confirm that the required .NET features are enabled.

​
Confirm the Target Is a .NET Process

Run:
This displays running processes that have loaded a CLR and identifies whether each process uses:
  • Classic .NET Framework
  • Modern .NET Core or .NET 5 and later
If the target does not appear, it may not be a .NET process or may not yet have loaded the CLR.

​
Confirm the Application Architecture

A profiler DLL must match the target process architecture: The 64-bit profiler cannot attach to a 32-bit process. Both GermainUX packages can be installed on the same computer when both architectures must be monitored.

​
Confirm the Profiler DLL Location

The profiler DLL must remain in its installed directory with the related Agent components. Do not move or rename it independently.

​
.NET Profiler Attachment Fails Without Creating a Log

Typical symptoms include:
  • No germain-clr-agent-{pid}.log file is created.
  • CLRLogLevel is set to a value other than OFF.
  • germain-agent.log, at DEBUG or TRACE, reports an attachment failure such as “Catastrophic failure.”
This usually indicates that the failure occurred before the CLR Profiler could initialize its logger. The most common cause is that the target application’s Windows identity cannot write to LogPath. The Agent may run as an elevated administrator while the target application runs as another, less-privileged account. To resolve the issue:
1

Identify the account running the target application

2

Verify that it has write access to LogPath

3

If necessary, configure LogPath to use a directory writable by every monitored account

4

Restart the Agent

5

Restart the target application

6

Check whether a new profiler log appears

Also confirm that the installed profiler architecture matches the application.

​
Use AgentConsole.exe

AgentConsole.exe is a standalone diagnostic utility installed with the GermainUX Agent and Code Profiler packages. It helps verify what Windows and the CLR expose before investigating Agent-specific behavior.

​
List Processes With a Loaded CLR

Run from an elevated Command Prompt:
The command lists:
  • Processes with a loaded CLR
  • Process IDs
  • Whether the process uses classic .NET Framework
  • Whether it uses .NET Core, .NET 5, or a later runtime
Use this command to confirm:
  • That the target is a .NET process
  • That the CLR is loaded
  • Which profiler attachment mechanism applies
  • Which process ID should have a corresponding CLR log

​
Display Available Commands

The options can vary between Agent versions. Use --help to obtain the command list available in the installed build.

​
Information to Collect for Germain Software Support

If the issue remains unresolved, collect:
  • GermainUX Agent version
  • Windows version and architecture
  • Target application name, version, executable name, and architecture
  • Target runtime, such as Win32, WPF, Windows Forms, .NET Framework, or modern .NET
  • Whether the rule is local or server-provided
  • The resolved JSON shown under Configurations
  • Relevant Registry settings
  • germain-agent.log
  • Applicable Windows UI worker log
  • Applicable CLR Profiler log
  • Target process ID
  • Output from AgentConsole.exe --list, when relevant
  • Approximate problem time and timezone
  • Steps required to reproduce the issue
  • Whether the issue affects every user or device
  • Any recent application, Agent, network, proxy, or security-policy change
Remove or protect confidential information before sharing diagnostic files.

​
Get Help

Contact GermainUX Support

The Germain Team can help you set this up.

Can't find what you need?

Search all GermainUX docs with Ctrl + K, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE LLC.