Troubleshooting manual license activation on unsupported Unity versions

Manually activated license files in the newer .xml format require Unity Licensing Client 1.18.3 or later. On Editor and Hub versions that bundle an older client, the license file fails validation both when you import it and when the Editor tries to load it. This page describes the symptoms, lists which versions include a compatible client, and explains how to activate the license on an Editor that you can't upgrade.

For the activation steps, refer to How do I manually activate my Unity license?.

Keep the following in mind about the license file:

• You obtain the license file through the manual activation flow at the manual activation portal: sign in, upload your license request file, activate the license for your assigned seat, and download the license file.
• Manual (offline) activation is available only for Enterprise and Industry seats. The activation page lists which of your assigned seats are eligible; you can't activate seats from other plans offline.
• The downloaded file is an .xml license named UnityEntitlementLicense-<timestamp>.xml, not the legacy .ulf format.
• Each activation lets you download the license file once. If you lose the file or need it again, repeat the activation steps. You can activate again for the same machine.

Symptoms

The failure appears in one of two ways, depending on whether you're importing the license file or the license is already activated on the machine.

Failure at import

When you try to import the license file with an unsupported version, Unity Hub shows the error Unable to save the license file. If you import from the Editor command line instead (-manualLicenseFile), the Editor log contains an error similar to the following.

[Licensing::Module] Loading manual activation license file .../UnityEntitlementLicense-20260818142817.xml. 
[Licensing::Client] Error: LicenseImportResponse reported an error: 
    ResponseCode: 500 
    ResponseStatus: An unexpected error occurred while processing the request

In both cases, the Licensing Client log contains an error similar to the following.

INFO  - [LicenseImportController] Trying to import license file: .../UnityEntitlementLicense-20260817194605.xml...
ERROR - [ApiPipeHandler#1] REQ-13 | Unable to process IPC message from Hub:
        [500 InternalServerError] An unexpected error occurred while processing the request
System.NotImplementedException: This method will be implemented later.
  at Unity.Licensing.Client.Communication.Controllers.LicenseImportController.ImportEntitlementBasedLicense(String licensePath)

Failure at load

If the license file is already activated on the machine (for example, through a supported Unity Hub) and an older Licensing Client then tries to load it, the client can't parse the manually activated license type. The Editor behaves as if no valid license is present, and the Licensing Client log contains an error similar to the following.

ERROR - [LicenseFilesMapper] Exception caught while parsing license .../UnityEntitlementLicense-20260818142817.xml
System.InvalidOperationException: There is an error in the XML document.
---> System.InvalidOperationException: Instance validation error: 'AssignedManual' is not a valid value for LicenseType.
  at Unity.Licensing.EntitlementResolver.License.UnityLicense.ReadAndParseLicense(Stream licenseStream, X509Certificate2 certificate)
  at Unity.Licensing.Client.Services.Helpers.LicenseFilesMapper.MapLicenseFilesToResult(IEnumerable`1 files, Boolean ignoreUlfLicenseFiles)

The Licensing Client log (Unity.Licensing.Client.log) is located at:

• Windows: %LOCALAPPDATA%\Unity\Unity.Licensing.Client.log
• macOS: ~/Library/Logs/Unity/Unity.Licensing.Client.log
• Linux: ~/.config/unity3d/Unity/Unity.Licensing.Client.log

Cause

Editors and Hubs that bundle Unity Licensing Client 1.18.2 or earlier can't load a manually activated Named User License: the bundled client doesn't recognize this license type.

The following table lists which versions of the Unity Editor, Unity Hub, and Unity Licensing Client support manually activated .xml license files.

Resolution: upgrade to a supported version

This is the recommended resolution. Upgrade to Unity Hub 3.21.1 or later, or to a supported Unity Editor version from the version support table, then activate normally.

If you can't upgrade, replace the Editor's bundled Licensing Client, as described in the following section.

Resolution: replace the bundled Licensing Client in Unity Editor

If you can't upgrade the Editor, replace its bundled Licensing Client with version 1.18.3 and import the license from the command line.

Download Unity Licensing Client 1.18.3

The following official standalone builds are available (build 1.18.3.d7ffd15):

Replace the client and import the license

To replace the bundled Licensing Client, follow these steps:

1. Close the Unity Editor and Unity Hub.

2. Download the 1.18.3 archive for your platform.

   Use the download links and pick the build matching your operating system and CPU architecture.

3. Locate the bundled Licensing Client in your Editor installation.

   • Windows: <Unity Editor installation>\Editor\Data\Resources\Licensing\Client\
   • macOS: <Unity Editor installation>/Unity.app/Contents/Helpers/UnityLicensingClient.app/Contents/MacOS/
   • Linux: <Unity Editor installation>/Editor/Data/Resources/Licensing/Client/

   These paths apply to Unity 2022.3 LTS through 6000.x. Only Unity 2020.x and older placed the client under Unity.app/Contents/Frameworks/ on macOS.

4. Back up the existing client folder.

   Rename Client to Client.bak (Windows and Linux), or UnityLicensingClient.app to UnityLicensingClient.app.bak (macOS). Rename rather than copy: the new client must extract into an empty folder, because files left over from the old version break the client's signature.

5. Extract the archive in place of the client you renamed.

   On Windows and Linux, unzip the archive into a new Client folder next to your backup. The archive holds the client's files directly, with no enclosing folder.

   On macOS, the archive holds the client app bundle's whole Contents folder, so extract it over UnityLicensingClient.app itself, not into Contents/MacOS/. Use ditto rather than the Finder or unzip: the client's .NET libraries carry their code signatures in extended attributes, which only ditto restores. Extracted any other way, the client is unsigned and macOS can refuse to run it.

   ditto -xk --noqtn <path-to-downloaded-archive>.zip \
     "<Unity Editor installation>/Unity.app/Contents/Helpers/UnityLicensingClient.app"

6. Verify the replacement.

   Run the client binary with --version. It must report 1.18.3 or later.

   # macOS
   <Unity Editor installation>/Unity.app/Contents/Helpers/UnityLicensingClient.app/Contents/MacOS/Unity.Licensing.Client --version
   
   # Windows / Linux (from the Client folder)
   Unity.Licensing.Client --version

7. Import the license file.

   Use the Editor command line:

   Unity -batchmode -manualLicenseFile <path-to-your-license-file> -logfile

   This command imports the license through the Editor's replaced client. Unity Hub's Activate with license file option uses the client bundled with the Hub, not the one you replaced, so it only works with a supported Hub version.

If the import still fails after you verify that the client reports 1.18.3 or later, contact Unity support and attach your Unity.Licensing.Client.log (locations listed in Symptoms) along with your Editor and Hub versions.