Build Troubleshooting in Open 3D Engine

This guide will help you identify and resolve some common issues that you might encounter with the Open 3D Engine (O3DE) build system. Be aware that you might come across situations unique to your project or build that aren’t addressed here. This reference is only for the most frequent build issues that aren’t affected by a known bug, or can’t easily be worked around. If you don’t find your problem covered here, try searching our forums or asking in the O3DE Discord .

If you believe your build problem is due to a bug in O3DE, check existing bug reports and file an issue if you can!

Looking for error logs or memory dumps? Refer to Open 3D Engine Log Files for locations.

C2027 Errors on Generated Files

Issue: The MSVC C2027 compiler error is caused by attempting to build a file referencing a missing type. This issue is normally caused by empty files created by the code generation tool, most often during the build of the AzQtFramework library.

Remedy:

1. Ensure that you have enough disk space to build your selected targets. The code generator will produce empty files if there isn’t enough disk space to write them.

2. Delete directories containing CMake cache information.

3. Delete folders containing autogenerated source from your build folder. Do one of the following:

   • Delete all folders containing _autogen in their name from your build directory.
   • Delete the build directory used during CMake configure and generate, then reconfigure and regenerate.

CMake Searching for Wrong MSVC During Configure

Issue: The CMake tools report a missing MSVC compiler. This produces a warning similar to:

CMake Error at CMakeLists.txt:15 (project):
  The CMAKE_C_COMPILER:
 
    C:/Program Files (x86)/Microsoft Visual Studio/2019/Professional/VC/Tools/MSVC/14.24.28314/bin/Hostx64/x64/cl.exe
 
  is not a full path to an existing compiler tool.

This is caused when Visual Studio is updated or modified, and the CMake cache holds information pointing to the previous compiler install.

Remedy: This issue is most often caused after a Visual Studio update, without a regeneration of the O3DE project files. The path of the C and C++ compiler is set at configure-time by the CMake system, using the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER values. These values are stored in the CMake cache. Clean the cache and reconfigure by doing one of the following:

• Removing the CMakeCache.txt file in your CMake build directory.
• Removing the CMake build directory completely.

After cleaning the cache, the correct compiler should be detected during the CMake configuration stage.

CMake fails to find Findo3de.cmake

Issue: The CMake tool reports it cannot find a package configuration file provided by “o3de”. This produces a warning similar to:

CMake Error at CMakeLists.txt:10 (find_package): 

By not providing "Findo3de.cmake" in CMAKE_MODULE_PATH this project has 
asked CMake to find a package configuration file provided by "o3de", but 
CMake did not find one. 

Could not find a package configuration file provided by "o3de" with any of 
the following names: 

o3deConfig.cmake 

o3de-config.cmake

Remedy: This issue is usually caused by a misconfigured o3de_manifest.json file that has an entry for a version of O3DE that no longer exists or has missing or corrupt files. This can occur if you installed O3DE and then deleted the engine folder instead of uninstalling it using “Add or Remove Programs”. Do the following:

1. Close Project Manager (o3de.exe) if it is open.
2. Open <user>/.o3de/o3de_manifest.json in a text editor.
3. Remove entries in the “engines” and “engines_path” lists for engines that have been removed or with paths that no longer exist.
4. Make sure that the final lines in “engines” and “engines_path” do not end in a comma.
5. Save and close the file.
6. Restart Project Manager (o3de.exe).
7. Re-add your project if you don’t see it in the Projects page.

When Project Manager opens it should automatically re-register the O3DE engine and update o3de_manifest.json with the correct information.

Package Directory Detection Fails

Issue: During configuration, the package directory isn’t correctly detected and the CMake configure task reports an error similar to the following:

cmake -B build/windows -S . -G "Visual Studio 16" -DLY_3RDPARTY_PATH="C:\o3de\3rdParty\"
-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.17763.
-- Using Windows target SDK 10.0.18362.0
CMake Error at cmake/3rdParty.cmake:19 (file):
  file FILE([TO_CMAKE_PATH|TO_NATIVE_PATH] path result) must be called with
  exactly three arguments.
Call Stack (most recent call first):
  CMakeLists.txt:43 (include)CMake Error at cmake/3rdParty.cmake:21 (if):
  if given arguments:    "NOT" "EXISTS" "C:/o3de/3rdParty\"  Unknown arguments specified
Call Stack (most recent call first):
  CMakeLists.txt:43 (include)-- Configuring incomplete, errors occurred!

Remedy: This issue is caused on Windows when the LY_3RDPARTY_PATH value passed to CMake ends in a \ character. Do one of the following:

• Change the value to remove the trailing \.
• Change the format of your LY_3RDPARTY_PATH to use the platform-agnostic / path separator.

Long build times

Issue: Building takes longer than expected.

Remedy: There are several steps to troubleshooting builds that are taking a long time.

1. Use a build command that measures the amount of time taken so you can compare build times when troubleshooting. On Windows you can use the PowerShell measure-command to measure build times, and on Linux you can use time.
   • Windows
   • Linux

   measure-command { cmake --build build/windows --target Editor AutomatedTesting.GameLauncher --config profile | Out-Default}
   

   time cmake --build build/linux --target Editor AutomatedTesting.GameLauncher --config profile 
   

2. Make sure you are only building the targets you are using. For example, select an appropriate target like the Editor for building and not the ALL_BUILD target which will build everything and take longer. Keep in mind that your first build will take the longest because all the code for the selected target and dependencies must be compiled, but subsequent builds should be much faster (minutes or seconds) especially when writing game code.
3. Use the profile build configuration when developing when you don’t need all the un-optimized debugging information of a debug build configuration.
4. Make sure you’re using unity builds (on by default) by configuring with the option -DLY_UNITY_BUILD=ON.
5. Don’t build unit tests if you aren’t making engine changes by configuring with the option -DLY_DISABLE_TEST_MODULES=ON.
6. Deactivate Gems that your project does not need using the O3DE CLI or Project Manager.
7. See the troubleshooting step for configuring compiler-specific settings below which might be necessary on hardware with high CPU core counts.

Building causes computer to freeze, lock up or reboot

Issue: On some computers, especially those with CPUs that have high core counts, the way that compilation is spread across cores can lead to resource starvation and even freezing. It’s also possible that a build could run out of memory and cause issues including resource starvation and reboot.

Remedy: If possible, adjust the build settings to spread out the maximum number of parallel processes used and the maximum CL processor counts allowed per project.

• Windows
• Linux

cmake --build build/windows --target Editor --config profile -- /m:16 /p:CL_MPCount=32

measure-command { cmake --build build/windows --target Editor --config profile -- /m:8 /p:CL_MPCount=8 | Out-Default}

Days              : 0
Hours             : 0
Minutes           : 15
Seconds           : 56
Milliseconds      : 701
Ticks             : 9567014354
TotalDays         : 0.0110729332800926
TotalHours        : 0.265750398722222
TotalMinutes      : 15.9450239233333
TotalSeconds      : 956.7014354
TotalMilliseconds : 956701.4354

cmake --build <build-dir> -j 6 --config profile --target MyProject.GameLauncher -- <generator specific options>