Skip to main content
Version: v3

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:

  1. Visit license.unity3d.com and upload the Unity_v20XX.X.XXXX.alf file.
  2. 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.
  3. Find the line of HTML that looks like this: <div class="option option-personal clear" style="display: none;">.
  4. Delete display: none; from the style attribute to make the "Personal" option visible.
  5. 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

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

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 and v1.x.x are out of date as we moved to Version 2 as shown on github.com/game-ci/docker/releases. We are not publishing images for v0.x.x or v1.x.x anymore.

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

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-2
# 2021.3.0f1-android-2: Pulling from unityci/editor
# [...]

Github Actions​

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

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

Gitlab CI​

Set the IMAGE_VERSION to 2 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.

  1. Ignore the dirty branch and continue the build. We have a parameter for that: allowDirtyBuild but ⚠️ it is not recommended.

  2. 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​

  1. 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.

  2. 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.

  3. 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.

This revised section provides a clearer understanding of the issue and offers more directed solutions.

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. 😉