Troubleshoot Build Automation failures

Check the logs for errors

The first step to troubleshoot any Unity Build Automation (UBA) failure is to check the error logs.

The UBA logs highlight error messages in red and warnings in yellow to improve visibility. UBA also collects any warning and error messages in a compact log tab to make them easier to find, although not all failures are recorded in the compact log so it can be helpful to check the full log. If there are multiple error logs and you have a previous build that was successful, you can compare the logs to filter out any errors that might be present in the successful run.

Run a clean build

UBA builds that cache either the library or the workspace folders can cause issues. To force the target to ignore the cache, use the Clean Build option when you trigger the build.

Run locally in batch mode

If the project builds successfully in the editor but fails to build through Unity Build Automation, it might be because you use batch mode to generate the build. To find out if the error reproduces, you can try to run in batch mode locally

First, you need to either delete the Library folder or check out the source code into a new fresh folder, which forces UBA a re-download of the packages. This simulates the UBA build server's behavior that checks out the source code on every build.

Here's a Windows and macOS version of the same command.

Note: Several of these flags are not required. If you don't want to run unit tests, you can skip the flags such as the -testPlatform, -testResults, and -runTests.

The directories provided are the default installation folders for the Unity Editor; adjust them according to the correct path on your local machine.

Windows CMD console

"C:\Program Files\Unity\Hub\Editor\{UNITY_VERSION}\Editor\unity.exe" -batchMode -skipMissingProjectID -skipMissingUPID -buildTarget {BUILD_TARGET} -logFile C:\{SOME_PATH}\log.txt -projectPath C:\{PROJECT_PATH} -executeMethod {CLASS_AND_STATIC_METHOD_NAME_OF_BUILD_SCRIPT} -quit

macOS terminal

/Applications/Unity/Hub/Editor/{UNITY_VERSION}/Unity.app/Contents/MacOS/Unity -batchMode -skipMissingProjectID -skipMissingUPID -buildTarget {BUILD_TARGET} -logFile /Users/{SOME_PATH}/log.txt -projectPath /Users/{PROJECT_PATH} -executeMethod {CLASS_AND_STATIC_METHOD_NAME_OF_BUILD_SCRIPT} -quit

If you'd like to also run tests, you can add the following tags:

  • -runTests
  • -testPlatform {PLATFORM} // playmode or editmode
  • -testResults {FILE_PATH_AND_FILE_NAME}.xml

Template build script

Place your build script containing the static method that performs the build inside the editor folder. If you don't have an editor folder yet, create one.

Here is a template build script for your reference:

using UnityEditor;
class MyEditorScript
{
  static void PerformBuild ()
  {
    BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions();
    buildPlayerOptions.scenes = new[] {"Assets/Scenes/MyScene.unity", ...};
    buildPlayerOptions.target = BuildTarget.iOS; // More details on BuildTarget doc
    buildPlayerOptions.options = BuildOptions.None;
    buildPlayerOptions.locationPathName = "iOSBuild";
    BuildPipeline.BuildPlayer(buildPlayerOptions);
  }
}

Common issues

General:

Platform specific issues:

Unity logo Documentation
Copyright © 2025 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.