Troubleshooting & Known Issues

This page covers common problems and known issues you may encounter while using the pipeline.

---

Known Issues

⚠️ Global Build Configuration (BuildConfiguration.xml)

To ensure the correct Visual Studio toolchain is used for each engine version, the script temporarily modifies the global BuildConfiguration.xml file located in Documents/Unreal Engine/UnrealBuildTool.

The script creates a backup and is designed to restore it, even if the build fails. However, if the script is terminated abruptly (e.g., by a system crash), the backup may not be restored. This could potentially affect other Unreal Engine projects on your system.

Mitigation: If you suspect this has happened, you can manually restore the configuration by deleting BuildConfiguration.xml and renaming BuildConfiguration.xml.bak to BuildConfiguration.xml in the above directory.

---

Common Errors

“Banned” C++ Compiler Error: UnrealBuildTool has banned the MSVC [version] toolchains...

• Cause: Epic Games has blocked a specific compiler version due to bugs.
• Solution: Open the Visual Studio Installer, go to “Individual components”, and install the exact MSVC version recommended in the error message.

Zipping Fails with “Stream was too long”:

• Cause: PowerShell’s built-in Compress-Archive command cannot handle files larger than 4GB.
• Solution: We recommend installing 7-Zip. You can then modify the Compress-Archive commands in the scripts to use the 7z.exe command-line tool, which has no file size limits.

Configuration Validation Fails:

• Solution: Run the validation script directly to see specific issues: .\Tools\validate_config.ps1 -ConfigPath "config.json"
• Common issues:
  • Missing Unreal Engine installations at specified paths.
  • Incorrect plugin source directory path.
  • Missing rclone executable (if cloud upload is enabled).
  • Invalid JSON syntax in config.json.

Pipeline Fails During Build:

• Check build logs: Look in the Logs/ directory (created at the project root) for detailed error messages from Unreal’s build tools.
• Common causes:
  • Your plugin’s source code has compilation errors.
  • You are missing the required Visual Studio toolchains for the target engine versions.
  • Insufficient disk space for temporary build files.