Troubleshooting HCL Local License Server

Log Files for Troubleshooting

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

Log File Description
hcl_lls.log Logs installation and runtime errors such as fingerprint mismatch, FQDN or TLS issues, and port conflicts.
hcl_lls_features.log Contains details about license leases, active features, and pool information.
hcl_lls_pools.log Updates whenever you add or remove license files, showing active license pools.

You can troubleshoot some common issues that you might encounter during the installation or operation of HCL Local License Server (LLS).

Common Issues and Resolutions

1. Fingerprint Mismatch

A fingerprint mismatch typically occurs when the system’s hardware or configuration no longer matches the parameters used during the original fingerprint generation.

Causes:

  • The network adapter (and its MAC address) used during fingerprint creation is no longer available or has been disabled/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.

Resolution:

  • Ensure that stable and permanent network interfaces (such as wired Ethernet adapters) are active during LLS installation or deployment.

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

  • If a fingerprint mismatch occurs:

    • Re-enable the original network adapter used during fingerprint generation, or

    • Regenerate the fingerprint and update the license accordingly.

Note:

  • LLS does not monitor Wi-Fi on/off status after installation.

  • Verification relies only on the presence of the MAC address that was used when the fingerprint was generated.

2. 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 using the built-in utility program, or use a valid third-party CA-signed certificate.

Ensure the Common Name (CN) in the certificate matches the configured FQDN.

3. Hostname or FQDN Validation Failure

Cause:

The Fully Qualified Domain Name (FQDN) entered during installation or update is invalid or unresolved.

Example error:

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

Resolution:

  • Ensure that the FQDN follows proper format (must contain at least one dot and not begin or end with a dot).

  • Add hostname-to-IP mapping if DNS resolution is unavailable:

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

    • Linux: /etc/hosts

Example hosts entry:

192.168.1.25 myllsserver.example.com

4. FQDN Validation Issues

This error occurs when the Fully Qualified Domain Name (FQDN) entered during installation does not meet required format conditions or cannot be resolved.

Cause:

  • The entered FQDN does not meet the required format (for example, missing a dot, invalid characters, or incorrect structure), or
  • You are installing LLS in a local/offline/test environment where a proper resolvable domain name is not available.

Resolution:

A. Correct the FQDN

Ensure the FQDN follows the required validation rules:

  • FQDN must not be empty.

  • Must not contain spaces or invalid characters
  • Must match the CN (Common Name) of the TLS certificate After correcting, retry the installation.

  • Total length ≤ 253 characters.

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

  • Must contain at least one dot ( . ) — minimum two labels required (e.g., server.domain).

  • Consecutive dots ( .. ) are not allowed.

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

  • Each label (portion between dots):

    • Must be 1–63 characters long.

    • Cannot start or end with a hyphen ( - ).

  • TLD (last label) cannot be all numeric.

  • At least two labels are required (e.g., domain.tld).

  • If FQDN contains xn--, it indicates a Punycode domain (used for internationalized domain names).

B. Bypass FQDN ValidationIf 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.
Steps to Skip FQDN Validation
  1. Navigate to the installer directory.
  2. Run one of the following commands:
Windows:

start utility.bat --skip-fqdn-validation

Linux:

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

5. License File Not Loaded or Missing Pools

Cause:

The license file was not copied correctly or does not match the active fingerprint.

Resolution:

  • Copy the valid license file to <installation_directory>/license.

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

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

Summary

Issue Possible Cause Resolution
Fingerprint mismatch License file fingerprint mismatch Regenerate fingerprint and re-download license
TLS certificate expired Certificate invalid/expired Generate new self-signed or third-party certificate
FQDN validation failed Invalid or unresolvable hostname Correct FQDN or use skip validation
Invalid FQDN format Missing dot, invalid characters Correct format or skip validation
License file not loaded Missing or mismatched license Verify license folder and MHS deployment

Results:

You can now identify and resolve most installation and configuration issues in HCL Local License Server 5.3.