Troubleshooting HCL Local License Server

Log Files for Troubleshooting

The following files are created in the installation directory. These help you identify and resolve installation or runtime issues.

For a Docker deployment, you can also read the logs from the container:

docker compose logs -f
docker exec hcl-lls-server cat /app/installer.txt
docker exec hcl-lls-server cat /app/service.log

For a native installation, the service messages are also available from the operating system: use Event Viewer (eventvwr.msc) on Windows, or the following command on Linux:

journalctl -u HCL-Local-License-Server-5.4.0.service

To change how much detail is written to the log files, see Log Configuration.

Fingerprint mismatch

A fingerprint mismatch typically occurs when the system configuration no longer matches the parameters used when the fingerprint was originally generated.

Causes on a native installation

• The network adapter, and its MAC address, used during fingerprint creation is no longer available or has been disabled or removed.

• The LLS port number has changed after installation.

• The fingerprint was generated using a temporary or unstable adapter, such as Wi-Fi, which may be turned off or unavailable during validation.

Causes on a Docker deployment

• The port number was changed after the license file was generated, either by running the update.bat/sh file or by editing the .env file.

• The database folder was deleted or replaced, which generates a new per-instance value.

On a Docker deployment, the fingerprint is stable across the following actions:

Resolution

• Retrieve the current fingerprint from the installer.txt file and re-generate the license file in My HCLSoftware (MHS). See Post-installation: Generating the license file.

• On a native installation, ensure that stable and permanent network interfaces, such as wired Ethernet adapters, are active during LLS installation.

• Avoid generating fingerprints using transient or removable adapters such as Wi-Fi dongles or virtual adapters.

• If a mismatch occurs on a native installation, re-enable the original network adapter used during fingerprint generation, or regenerate the fingerprint and update the license accordingly.

TLS certificate expired or invalid

Cause

An expired or invalid TLS certificate was used during installation or configuration.

Resolution

Generate a new self-signed TLS certificate by running the utility.bat/sh file, or use a valid third-party CA-signed certificate. For third-party certificates, contact your local IT team. Ensure the Common Name (CN) in the certificate matches the configured FQDN, then apply it by running the update.bat/sh file. See Configuring HCL Local License Server.

Hostname or FQDN validation failure

Cause

The Fully Qualified Domain Name (FQDN) entered during installation or update is invalid, does not meet the required format, or cannot be resolved. This also occurs when you install LLS in a local, offline, or test environment where a resolvable domain name is not available.

An example error is:

curl: (51) SSL: no alternative certificate subject name matches target host name

Resolution 1: correct the FQDN

Ensure the FQDN follows the required validation rules:

• Must not be empty.

• Must not contain spaces or invalid characters.

• Must match the Common Name (CN) of the TLS certificate.

• Total length must be 253 characters or fewer.

• Cannot start or end with a dot ( . ).

• Must contain at least one dot ( . ). A minimum of two labels is required, for example server.domain.

• Consecutive dots ( .. ) are not allowed.

• Allowed characters are letters (A-Z, a-z), digits (0-9), dots ( . ), and hyphens ( - ).

• Each label, that is each portion between dots, must be 1 to 63 characters long and cannot start or end with a hyphen ( - ).

• The last label cannot be all numeric.

• An FQDN that contains xn-- indicates a Punycode domain, used for internationalized domain names.

If DNS resolution is unavailable, add a hostname-to-IP mapping to the hosts file:

• On Windows: C:\Windows\System32\drivers\etc\hosts

• On Linux: /etc/hosts

An example hosts entry is:

192.168.1.25 myllsserver.example.com

After correcting the FQDN, retry the installation.

Resolution 2: bypass FQDN validation

If you are setting up LLS in a local, offline, or non-production environment where a resolvable domain is not available, you can skip FQDN validation. Go to the installer directory and run one of the following commands:

utility.bat --skip-fqdn-validation
./utility.sh --skip-fqdn-validation

License file not loaded or missing pools

Cause

The license file was not copied correctly, cannot be read by the server, or does not match the active fingerprint.

Resolution

• Copy the valid license file to <lls_install_directory>/licenses.

• Verify the deployment and license allocation in My HCLSoftware (MHS).

• Check the hcl_lls_pools.log file to confirm successful initialization.

• On a Docker deployment, check the file permissions. The container runs as a non-root user and cannot change file permissions itself. If hcl_lls.log reports a permission error, run chmod 644 licenses/*.license on the host. On VirtualBox shared folders and SMB or CIFS mounts, chmod has no effect; set the permissions in the mount options instead, for example fmode=644 or file_mode=0644.

Container stops immediately after starting

Cause

An invalid TLS certificate path, a port that is already in use, or a missing config.json file.

Resolution

Check the container logs:

docker compose logs

Verify that the port is not in use:

ss -tlnp | grep <port>          # Linux
netstat -ano | findstr :<port>   # Windows

Port already in use

Cause

Another process on the host is already using the configured port. On a Docker deployment the container publishes its port on the host, so a conflict on the host prevents the container from starting.

Resolution

Change the port by running the update.bat/sh file. See Configuring HCL Local License Server. Changing the port regenerates the fingerprint, so you must generate a new license file in My HCLSoftware (MHS).

TLS mode not taking effect

Resolution

• On a Docker deployment, ensure that config.json is in the same folder as docker-compose.yml.

• Check that the value is BASIC, SECURED, or MODERN. The values are case-sensitive.

• Restart the LLS service after changing the value. See TLS Security Configuration.

Log files not updating after a backup restore or version upgrade on a Windows Server native installation

Symptom

The files in the logs folder stop updating. Licensing continues to work normally and no message is displayed. In service.log in the installation directory, the entries end with Access is denied.

Applies to

• Windows Server native installations in which the installer restored the certificates, licenses, logs, and port from a backup. This happens when you answer Y at the restore prompt, and on every version upgrade, because an upgrade always creates a backup of the existing installation and restores it onto the new installation automatically.
• Windows 11 installations are not affected.
• Docker deployments are not affected.
• Linux installations are not affected.

Cause

The LLS service runs under the built-in Windows LocalService account, which is deliberately low-privilege. It can write the files that it creates itself, but not the files that the installer places in the installation directory, because the installer runs elevated. The default drive-root permissions grant the required access on Windows 11, but the Windows Server defaults do not.

Workaround

Run the following command in an administrator Command Prompt, and then restart the LLS service:

icacls "<installation directory>" /grant "*S-1-5-19:(OI)(CI)M" /T

For example:

icacls "C:\HCL_LLS5.4" /grant "*S-1-5-19:(OI)(CI)M" /T

The command grants Modify access to *S-1-5-19, the well-known security identifier of the LocalService account, for the installation folder and its contents. No other account is affected.

For what an installation restores from a backup, see Backup and Restore.

Summary