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 in GitHub 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 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.

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.

Once your package is in a repository, see the Dependencies documentation for how to access it from your build workflow.

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.

See our documentation on Dependencies for more information on how to access submodules and private UPM packages from your build workflow.

By default, the build artifact will be expired after 1 day. You can change the expiration time by setting the retention-days parameter in the upload-artifact step in your build workflow.

See documentation for upload-artifact for more information.

You can add additional modules to the unity-setup step of your workflow, for example modules: ios.

See documentation for upload-artifact for more information.

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 MacOS projects.

This error can show up during the activate-unity-license step.

• Ensure the UNITY_USERNAME and UNITY_PASSWORD secrets are set correctly in your GitHub settings.
• 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 activate-unity-license.