Troubleshooting

Run a build once in on your development machine to ensure your project is set up to build successfully. You may realize that you forgot to select a scene or that a script doesn't build for a particular platform.

If the build succeeds locally, but fails on the build machine, then check if your project has any local package or submodule dependencies that are not available to the build machine.

There are many parts in the Unity build toolchain and some of them can be nondeterministic. Try running the build again to see if the problem 'magically' resolves itself.

When a run is complete, go to the 'Summary' page to see logs and artifacts. Buildalon Actions generate a summary that will display warnings and errors.

When focusing on a specific job, there is a search bar in the top right of the log display. Searching “error” or “failed” can take you right to the problem.

Buildalon Actions generate a log files that can be uploaded as artifacts, even when the build fails. If you used auto-start to generate your workflow, the 'Upload Artifacts' step will do this for you.

You can download the artifacts from the 'Summary' page of the run. Learn more about how to download the workflow artifacts here.

In your Unity Project, ensure there are scenes selected under File > Build Settings > Scenes In Build.

Try updating your Unity project to the latest version of the LTS release you're using. We've seen this issue on version 2021.3.22 when building building a MacOS projects.

This error can show up during the activate-unity-license step. Ensure the UNITY_USERNAME and UNITY_PASSWORD secrets are set correctly. If using a professional license, set the license in the activate-unity-license step to Professional and ensure the UNITY_SERIAL secret is set correctly. Professional licenses can only be used on two machines at a time. Learn more about about activate-unity-license.

Your Buildalon runner won't be able to access packages on your local disk.

We recommend moving local packages to their own repository. Your Unity project can add a reference to the package with a git reference. Our comprehensive guide to Git and Unity has a section on the topic.

Ensure your project has unit tests and that they run successfully locally.

If you try to run Edit Mode Tests without the NUnit package installed, Unity will hang. Remove the Edit Mode Tests step from your workflow.

To have the build machine check out submodules, add the submodules: 'recursive' to the checkout action in your workflow. For example:

- uses: actions/checkout@v4
    with:
      submodules: 'recursive'

There are more steps involved when these submodules are private.

• Create a fine-grained personal access token so the workflow can access it.
• Add this permission: Repository > Contents > Read-only.
• Go to your organization's Secrets & Variables and add a secret with the name CI_TOKEN and the value of your personal access token.

If the submodule is owned by an organization, then the organization must also allow private access tokens.

Ask each submodule's organization owner to go to Settings > Personal Access Tokens > Settings and allow fine-grained access tokens.

Afterwards, the above example should be expanded to:

- uses: actions/checkout@v4
    with:
      submodules: 'recursive'
      token: ${{ secrets.CI_TOKEN }}