Version: v4 (current)

Common issues

Below you'll find a collection of answers to commonly reported problems.

Unity Activation

If you are having troubles with activation, you are not alone, this is a common problem, and it is not the easiest thing to solve. Here are some tips:

Try removing special characters from your password, sometimes they cause problems with command lines. This is not a security advice
Your username should be an email
Confirm you are able to connect on Unity's website using your credentials

caution

Unity no longer supports manual activation of Personal licenses

When activating your Personal Unity license, you may encounter an issue where only the "Unity Pro or Plus" option is available, preventing the activation of a Personal license. Here is a workaround to resolve this:

Visit license.unity3d.com and upload the Unity_v20XX.X.XXXX.alf file.
On the "Activate your license" page, if the "Personal" option is not available, right-click on the page and choose "Inspect" to open the browser's developer tools.
Find the line of HTML that looks like this: <div class="option option-personal clear" style="display: none;">.
Delete display: none; from the style attribute to make the "Personal" option visible.
Now you should be able to select the "Personal" option and proceed with the activation.

You can discuss this issue or find additional assistance in the related Discord conversation or GitHub ticket.

For future reference, activating a license from the command line as documented on Unity's Manual Page might be an alternative solution.

Known issue with Unity activation on gitlab-ci: empty license file

If you are having troubles with Unity activation with gitlab-ci, there is currently an issue with recent Unity versions preventing us to retrieve a license file with actual content.

For more details see the following issue: get-activation-file succeeding but giving a 0kb file. Unity Version 2021.2.7f1 and the workaround.

Don't hesitate to contribute and implement a fix 💝

I cannot activate because

'Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼' during manual activation

When activating a license on license.unity3d.com, you may encounter the following error message:

Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼

Here's Unity's workaround:

Unfortunately, this is a known issue our end. The relevant team are in the process of working on a fix as we speak, in the meantime there is a workaround. Try renaming the alf file with a command to convert characters on it with a iconv command.

Solution

version=v2020.1.12f1 # update this according to your version and file name
iconv -f UTF-8 -t utf-16BE Unity_${version}.alf > Unity_${version}.utf16be.alf

If you are using google account you can have some issue with activating unity. You just need to go on the unity website, settings, security and change your password. Then use your Google email and your new password, and it will work just fine ;)

Source

The digital signature is invalid.

Error

Error: Code 400 while processing request (status: Cannot save ULF license file: Validation failed. The digital signature is invalid.)

Solution

Depending on the CI/CD system, storing multi-line file content into an environment variable can break the encoding. You can store the license as a base64 encoded string. Then during the pipeline execution, you decode it and write it to the right location afterward. For example, here is a fixed confirmed to be working on OneDev CI:

/bin/echo $UNITY_LICENSE > /opt/project/Unity_v2022.x.base64 \
  && base64 -d /opt/project/Unity_v2022.x.base64 > /opt/project/Unity_v2022.x.ulf

Reference: game-ci/documentation #300 Unity personal activation fails on OneDev CI

My workflow isn't working because

I get `manifest for unityci/editor:2021.3.0f1-android-0 not found: manifest unknown: manifest unknown`

This means the docker image trying to download from docker hub is not found.

Solution

To know which docker images are available, you can visit the list of all supported Unity versions here.

In this particular case, it is also important to look for the last part of the docker image which is the version for GameCI. -0 means it is the latest v0.x.x version of the docker images. v0.x.x, v1.x.x, and v2.x.x are out of date as we moved to Version 3 as shown on github.com/game-ci/docker/releases. We are not publishing images for v0.x.x, v1.x.x, v2.x.x anymore.

The correct image should be unityci/editor:2021.3.0f1-android-3.

You can also test this locally:

# wrong
docker pull unityci/editor:2021.3.0f1-android-0
# Error response from daemon: manifest for unityci/editor:2021.3.0f1-android-0 not found: manifest unknown: manifest unknown

# right
docker pull unityci/editor:2021.3.0f1-android-3
# 2021.3.0f1-android-3: Pulling from unityci/editor
# [...]

Github Actions

You need to make sure you are using Github Actions v4, check for the version of your actions in your .github/workflows/*.yml files.

- uses: game-ci/unity-builder@v3
+ uses: game-ci/unity-builder@v4

Gitlab CI

Set the IMAGE_VERSION to 3 in .gitlab-ci.yml

Scripts have compiler errors.

Error

Scripts have compiler errors.
(Filename: ./Runtime/Utilities/Argv.cpp Line: 361)

Aborting batchmode due to failure:
Scripts have compiler errors.

Solution

Likely you have a missing script or assembly.

Make sure your branch is clean and all files are indeed present:

No accidentally ignored files (i.e. ignored .tmp might match text mesh pro);
No tracked files that you expected to be ignored;
All packages listed;
No pre-build steps that change your project differently from how that happens locally;

A good way to verify this, is to (locally) clone the Unity project in a new folder and run the build from there.

Branch is dirty

Error

Branch is dirty. Refusing to base semantic version on uncommitted changes

This usually happens with GitHub actions when using unity-builder. A dirty branch means that you have uncommitted changes in your project. When you see this error in the logs of your pipeline, that means some files of your project are being modified after the build. This is not desirable as it could lead to unexpected results.

Solution

There are multiple options to solve this.

Ignore the dirty branch and continue the build. We have a parameter for that: allowDirtyBuild but ⚠️ it is not recommended.
Find the files that are being modified and fix the source of the problem. This is the recommended solution.
The log should list the files that are considered modified on the now dirty branch. First, double check that these are not temporary files created by the runners themselves (see the Preparing the Project section regarding .gitignore). If the files are instead project related, locate the modified files and figure out why they are being modified. Sometimes, it's because a .meta file gets modified by unity when you open the project. If this is the case you can try this:
1. Clone your project in a new folder
2. Open your project with unity
3. Build your project
4. Run git status and see if files were modified. If so, commit them.
You can also try to download the modified files from the pipeline by exposing them as artifact and looking at the diff yourself.
Something else you can try is moving and committing the file(s) to see if it makes a difference.

Gradle error

Error

Error: 3.690 [ERROR] [org.gradle.launcher.daemon.server.DaemonStateCoordinator] Command execution: started DaemonCommandExecution[command = Build{id=69dbd5b3-10f2-488e-8640-977da68733f9, currentDir=/github/workspace/Temp/gradleOut/launcher}, connection = DefaultDaemonConnection: socket connection from /127.0.0.1:33657 to /127.0.0.1:43866] after 0.0 minutes of idle

Solution

There are 2 possible solutions:

Remove emojis from all environment variables (and thus workflow files), or
Upgrade your project and workflow to use Unity editor version 2020.2 or later.

No space left on device

Error

Example when downloading an android docker image:

docker: failed to register layer: ApplyLayer exit status 1 stdout:  stderr: write /opt/unity/Editor/Data/PlaybackEngines/AndroidPlayer/NDK/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/9.0.8/lib/linux/x86_64/libFuzzer.a: no space left on device.

or when it's downloading a docker image for the windows target platform:

[...]
6fad6f1176e0: Verifying Checksum
6fad6f1176e0: Download complete
docker: failed to register layer: write /opt/unity/Editor/Data/Resources/PackageManager/BuiltInPackages/com.unity.visualeffectgraph/Documentation~/Images/EventContexts.png: no space left on device.

Explanation

When executing multiple jobs sequentially in the same workflow, there can be potential disk space issues. For instance, if your workflow first executes tests on one docker image, such as unityci/editor:ubuntu-2022.3.4f1-linux-il2cpp-2, and subsequently runs a build on another target platform, e.g., unityci/editor:ubuntu-2022.3.4f1-windows-mono-2, it might run out of space during the build phase.

This happens because each job might be downloading and using its separate docker image, which can collectively consume a significant amount of disk space.

Solution

Parallel Execution: A straightforward workaround is to execute the tests and builds in parallel rather than sequentially. This ensures that each runner (or CI job) utilizes its own docker image, thereby avoiding cumulative disk usage. By structuring your CI workflow to execute these jobs concurrently, each job can independently manage its disk space. You can refer to our Github 'Parallel execution of Tests and Builds' example.
Free Up Disk Space: Use the Free Disk Space (Ubuntu) action at the start of your workflow to clear some space on the GitHub-hosted runner. This action can be especially useful if only a small amount of additional space is needed.
Use Self-Hosted or Cloud Runners: If your project inherently requires more disk space than what GitHub-hosted runners provide, consider switching to Self-hosted Runners or Cloud Runners. This would give you more control over the resources and disk space.

Failed to find a suitable OpenCL device for the GPU Lightmapper

Error

Error: Failed to find a suitable OpenCL device for the GPU Lightmapper. Please change your lightmapper or install the latest graphics driver.

Error: Global Illumination requires a graphics device to render albedo.

Explanation

This error occurs when Unity fails to find a suitable OpenCL device for the GPU Lightmapper. This can be due to a variety of reasons, such as:

The GPU Lightmapper is not supported on the current hardware.
The GPU Lightmapper is not supported on the current operating system.
The GPU Lightmapper is not supported on the current Unity version.
The GPU Lightmapper is not supported on the current graphics driver.

In the context of CI/CD pipelines, this error can occur when running Unity in a headless mode on a virtual machine, a cloud-based CI/CD service, or a containerized environment as the GPU might not be available or supported.

Solution

You can change the lightmapper settings in your Unity project to use the CPU Lightmapper.

I went ahead and looked for that setting to make it easier for anyone else getting this error to figure out how to at least bypass the error or try something.

How to find the Lightmapper settings

The "Progressive GPU Lightmapper" setting in Unity is used for baking lightmaps using the GPU, which can significantly speed up the process compared to CPU lightmapping. This feature is especially useful for high-quality lighting in complex scenes, but might be missing when running in a Dockerized environment such as in a CI/CD pipeline with GameCI.

Here’s how to find and change the Lightmapper setting in Unity:

Open Unity and load your project.
Open the Lighting Window: Go to Window > Rendering > Lighting.
Lightmapping Settings: In the Lighting window (scene tab), you'll see a Lighting Settings section with a Lighting Settings Asset
Select the Lighting Settings Asset file: Clicking on the asset will highlight it in your Project window. Click on the asset to edit the values with the inspector.
Find the Lightmapping Settings: Look for a dropdown labeled Lightmapper. If Realtime Global Illumination and Baked Global Illumination aren't checked, the option won't be available (it will be grayed out). Here, you have the option to select between :
- Enlighten
- Progressive GPU (Preview)
- Progressive CPU
Bake the Lightmaps: After setting up your lightmapper, you can click Generate Lighting to start baking the lightmaps using the selected option.

Once the lightmapper is set to Progressive CPU, you should commit the changes to your project and re-run the pipeline to see if the error persists.

General tips

These are tips that are usually applicable to problems you may encounter while working with a game engine and CI/CD:

Try to isolate your problem as much as possible
Try with a blank project, this will help you to isolate your problem. Is it a something with your project specifically or is it with Unity or GameCI?
Try to search for error keywords in your message such as error, failed, exception, etc.
Read the error message closely to understand what's going on.

Still having problems?

You can search for existing issues:

You can open an issue on one of the related projects:

You can also visit us on discord. Discord also has a search feature. 😉

Common issues

Unity Activation​

I cannot activate because​

'Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼' during manual activation​

Solution​

I use my Google account to login to Unity, how do I get my username and password?​

The digital signature is invalid.​

Error​

Solution​

My workflow isn't working because​

I get manifest for unityci/editor:2021.3.0f1-android-0 not found: manifest unknown: manifest unknown​

Solution​

Github Actions​

Gitlab CI​

Scripts have compiler errors.​

Error​

Solution​

Branch is dirty​

Error​

Solution​

Gradle error​

Error​

Solution​

No space left on device​

Error​

Explanation​

Solution​

Failed to find a suitable OpenCL device for the GPU Lightmapper​

Error​

Explanation​

Solution​

General tips​

Still having problems?​

Unity Activation

I cannot activate because

'Non-whitespace before first tag. Line: 0 Column: 1 Char: 㼼' during manual activation

Solution

I use my Google account to login to Unity, how do I get my username and password?

The digital signature is invalid.

Error

Solution

My workflow isn't working because

I get `manifest for unityci/editor:2021.3.0f1-android-0 not found: manifest unknown: manifest unknown`

Solution

Github Actions

Gitlab CI

Scripts have compiler errors.

Error

Solution

Branch is dirty

Error

Solution

Gradle error

Error

Solution

No space left on device

Error

Explanation

Solution

Failed to find a suitable OpenCL device for the GPU Lightmapper

Error

Explanation

Solution

General tips

Still having problems?