지원되지 않는 Unity 버전에서 수동 라이선스 활성화 문제 해결

새로운 .xml 형식의 수동 활성화 라이선스 파일은 Unity Licensing Client 1.18.3 이상이 필요합니다. 이전 클라이언트가 포함된 Editor 및 Hub 버전에서는 라이선스 파일이 가져오기 시와 Editor가 로드 시 모두 유효성 검사를 통과하지 못합니다. 이 페이지에서는 증상을 설명하고, 호환 가능한 클라이언트를 포함하는 버전을 나열하며, 업그레이드할 수 없는 Editor에서 라이선스를 활성화하는 방법을 안내합니다.

활성화 절차는 내 Unity 라이선스를 수동으로 어떻게 활성화하나요?를 참조하세요.

라이선스 파일에 대해 다음 사항을 유의하세요:

• 라이선스 파일은 수동 활성화 포털의 수동 활성화 절차를 통해 얻습니다: 로그인 후, 라이선스 요청 파일을 업로드하고, 할당된 좌석에 대해 라이선스를 활성화한 다음, 라이선스 파일을 다운로드합니다.
• 수동(오프라인) 활성화는 Enterprise 및 Industry 좌석에만 제공됩니다. 활성화 페이지에서 할당된 좌석 중 활성화 가능한 좌석이 표시되며, 다른 플랜의 좌석은 오프라인으로 활성화할 수 없습니다.
• 다운로드된 파일은 레거시 .ulf 형식이 아닌 UnityEntitlementLicense-<timestamp>.xml 이름의 .xml 라이선스 파일입니다.
• 각 활성화는 라이선스 파일을 한 번 다운로드할 수 있게 합니다. 파일을 분실하거나 다시 필요하면 활성화 절차를 반복하세요. 동일한 머신에 대해 다시 활성화할 수 있습니다.

증상

실패는 라이선스 파일을 가져오는지, 아니면 이미 머신에 활성화된 라이선스인지에 따라 두 가지 방식 중 하나로 나타납니다.

가져오기 실패

지원되지 않는 버전에서 라이선스 파일을 가져오려 하면 Unity Hub에서 Unable to save the license file 오류가 표시됩니다. Editor 명령줄에서 가져오기(-manualLicenseFile)를 시도할 경우, Editor 로그에 다음과 유사한 오류가 기록됩니다.

[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

두 경우 모두 Licensing Client 로그에 다음과 유사한 오류가 포함됩니다.

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)

로드 실패

라이선스 파일이 이미 머신에 활성화되어 있고(예: 지원되는 Unity Hub를 통해) 이전 Licensing Client가 이를 로드하려 할 때, 클라이언트는 수동 활성화된 라이선스 유형을 파싱할 수 없습니다. Editor는 유효한 라이선스가 없는 것처럼 동작하며, Licensing Client 로그에는 다음과 유사한 오류가 포함됩니다.

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)

Licensing Client 로그(Unity.Licensing.Client.log) 위치는 다음과 같습니다:

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

원인

Unity Licensing Client 1.18.2 이하가 포함된 Editor 및 Hub는 수동 활성화된 Named User License를 로드할 수 없습니다: 포함된 클라이언트가 이 라이선스 유형을 인식하지 못하기 때문입니다.

다음 표는 수동 활성화된 .xml 라이선스 파일을 지원하는 Unity Editor, Unity Hub 및 Unity Licensing Client 버전을 나열합니다.

해결 방법: 지원되는 버전으로 업그레이드

이 방법이 권장됩니다. Unity Hub 3.21.1 이상 또는 버전 지원 표에 나열된 지원되는 Unity Editor 버전으로 업그레이드한 후 정상적으로 활성화하세요.

업그레이드할 수 없는 경우, 다음 섹션에 설명된 대로 Editor에 포함된 Licensing Client를 교체하세요.

해결 방법: Unity Editor에 포함된 Licensing Client 교체

Editor를 업그레이드할 수 없는 경우, 포함된 Licensing Client를 1.18.3 버전으로 교체하고 명령줄에서 라이선스를 가져오세요.

Unity Licensing Client 1.18.3 다운로드

다음 공식 독립 실행형 빌드가 제공됩니다 (빌드 1.18.3.d7ffd15):

클라이언트 교체 및 라이선스 가져오기

포함된 Licensing Client를 교체하려면 다음 단계를 따르세요:

1. Unity Editor와 Unity Hub를 종료합니다.

2. 플랫폼에 맞는 1.18.3 아카이브를 다운로드합니다.

   다운로드 링크를 사용하여 운영 체제와 CPU 아키텍처에 맞는 빌드를 선택하세요.

3. Editor 설치 폴더 내 포함된 Licensing Client 위치를 찾습니다.

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

   이 경로는 Unity 2022.3 LTS부터 6000.x까지 적용됩니다. Unity 2020.x 및 이전 버전은 macOS에서 클라이언트를 Unity.app/Contents/Frameworks/에 두었습니다.

4. 기존 클라이언트 폴더를 백업합니다.

   Windows 및 Linux에서는 Client 폴더 이름을 Client.bak로, macOS에서는 UnityLicensingClient.app을 UnityLicensingClient.app.bak로 이름을 변경하세요. 복사하지 말고 이름을 변경해야 합니다: 새 클라이언트는 빈 폴더에 압축 해제되어야 하며, 이전 버전의 파일이 남아 있으면 클라이언트 서명이 깨집니다.

5. 아카이브를 백업한 클라이언트 폴더 대신 압축 해제합니다.

   Windows 및 Linux에서는 아카이브를 새 Client 폴더에 압축 해제하세요. 아카이브에는 별도의 상위 폴더 없이 클라이언트 파일이 직접 포함되어 있습니다.

   macOS에서는 아카이브에 클라이언트 앱 번들의 전체 Contents 폴더가 포함되어 있으므로, Contents/MacOS/가 아닌 UnityLicensingClient.app 자체에 덮어써야 합니다. Finder나 unzip 대신 ditto를 사용하세요: 클라이언트의 .NET 라이브러리는 확장 속성에 코드 서명을 포함하고 있어 ditto만 이를 복원합니다. 다른 방식으로 압축 해제하면 클라이언트가 서명되지 않아 macOS에서 실행을 거부할 수 있습니다.

   ditto -xk --noqtn <다운로드한-아카이브-경로>.zip \
     "<Unity Editor 설치 경로>/Unity.app/Contents/Helpers/UnityLicensingClient.app"

6. 교체가 제대로 되었는지 확인합니다.

   클라이언트 실행 파일에 --version 옵션을 사용해 실행하세요. 1.18.3 이상을 보고해야 합니다.

   # macOS
   <Unity Editor 설치 경로>/Unity.app/Contents/Helpers/UnityLicensingClient.app/Contents/MacOS/Unity.Licensing.Client --version
   
   # Windows / Linux (Client 폴더에서)
   Unity.Licensing.Client --version

7. 라이선스 파일을 가져옵니다.

   Editor 명령줄을 사용하세요:

   Unity -batchmode -manualLicenseFile <라이선스-파일-경로> -logfile

   이 명령은 Editor에 교체된 클라이언트를 통해 라이선스를 가져옵니다. Unity Hub의 Activate with license file 옵션은 Hub에 포함된 클라이언트를 사용하므로, 교체한 클라이언트가 아닌 지원되는 Hub 버전에서만 작동합니다.

클라이언트가 1.18.3 이상을 보고하는지 확인한 후에도 가져오기가 실패하면 Unity 지원팀에 문의하고 Unity.Licensing.Client.log 파일(위 증상 섹션에 위치 나열)과 함께 Editor 및 Hub 버전을 첨부하세요.