Download

UGS Troubleshooting

Mar 3, 2021.Knowledge

For many issues that you experience within UGS, there could be a tooltip that gives you more information on what’s going wrong with an option you think should be working correctly.

Basic Troubleshooting
Gathering basic information about your setup to include when asking a question to either Epic or your IT department will help get you better, more efficient assistance. Some items like this include:

  • Establish if you can reproduce the issue without using UGS. Often, issues that appear to be UGS-related, are not. For example:
    • If there’s a crash, try opening the editor without using UGS.
    • If there’s a Perforce sync issue, try using only Perforce instead of using it through UGS.

If you still see the issue without UGS involved, you’ll need to contact the team or department responsible for where the issue is actually occurring to get better assistance.

  • Establish if you are on the latest version of UGS. Version information can be accessed through either the diagnostic menu ( Main page, Options → Diagnostics… ), or it can be found in C:\Users<user>\AppData\Local\UnrealGameSync\ in UnrealGameSync.log. This can often be the cause of issues involving metadata and updates to UGS.

  • If you’ve determined that this is a UGS-specific issue, please refer to the common issues below first.

Note:

A large number of Compile errors can be solved with simple troubleshooting steps:

  • Confirm which step in the Compile failed
    • ex: UnrealHeaderTool, ShaderCompileWorker, etc.
  • Clean Workspace through UnrealGameSync, by selecting “More → Clean Workspace” in the Project Overview area, and attempt to sync / compile again
  • Delete UE4.sln, manually run GenerateProjectFiles.bat (Windows), GenerateProjectFiles.command (Mac), and attempt to sync / compile again
  • Attempt to manually compile using Visual Studio / XCode
  • Attempt to sync / compile a Changelist marked as Good (green ball)
    • If failure continues, select Options > “Use Incremental Builds” = False
    • Attempt to recompile
  • Ensure “Sync Precompiled Editor” is disabled (Note: Only available in certain streams)
  • Confirm the workspace in Perforce has been configured properly
  • Warning: this can be helpful in a lot of situations, but it doesn’t cover if there are extra files within your workspace. If your workspace gets too complex to manage, you may need to contact your IT department for help, or remake your workspace and re-sync the data for it.

Can’t see precompiled binaries
Detecting PCBs can take a long time. UGS will first load all the CLs, then cross-reference them to see what PCBs are available. On a slower connection, this can take minutes, so don’t give up if it might be slow! Otherwise, this is likely a result of permissions issues with the stream where they’re stored, or they aren’t getting created/uploaded correctly due to a build health issue. Contact your P4 administrator and confirm your builds are successfully uploading the precompiled binaries, and that you have access.

The tooltip when hovering over “Sync Precompiled Binaries” will also give more information that’s helpful when debugging this issue:

Can’t connect
This is typically a Perforce or a local network issue. We’ve seen problems with version 2019.2, and it’d be worth changing away from that version to start. Sometimes using P4V to relog into your Perforce server can help with this too.

If this is during a first time setup, and you get the error:

Failed to sync application

And your log contains:

Couldn’t find last changelist

Make sure your “Depot Path” is set to the correct Perforce location provided to you by your Perforce administrator, and that the path is properly formatted like:

//depot/path/to/UnrealGameSync/bin

With the two leading slashes, denoting a Perforce depot, and no terminating forward slash. Then click “Connect” again.
If this is all set correctly, and your Perforce version is not 2019.2, you should contact your Perforce admin to confirm you have permissions for your depot path.

Failed sync or build due to too-long path
There’s a 260 character path limit on most Windows versions that UGS is unable to circumvent. In fact, if UGS detects a path that will be longer than 260 characters, it will block syncing a project entirely. There is currently no way to disable this check in UGS.

To help with this, you may need to set up your workspace in a folder that’s closer to the root ( I.E.: D:/prj/workspace/ ). Also, try to enforce a file naming structure that shortens your file names as much as possible.

This can also occur in rare instances if you’ve decided to sync your project using a .uprojectdirs file instead of a .uproject file. This can be worked around by instead setting up the project in UGS with a .uproject file.

Select “Settings”

Select “Browse” for both “Name” and “Path” of the Workspace you’re using
Example Name:

Example Path:

Then, instead of selecting a uprojectdirs file like in the setup tutorial, simply select a uproject file within that stream

Then attempt to sync again

UGS won’t auto-update

Case 1: This one is typically due to file contention on the machine. This can be solved by closing UGS, confirming there are no active UGS processes running, and deleting [AppData]/Local/UnrealGameSync/Latest/ which typically contains the files in contention that prevent the update.

If the deletion of that folder fails, you should be met with what file is held in contention and what process is holding on to it. If you’re unable to stop that process, rebooting should resolve that issue and allow you to delete that folder.

After, you can use the UnrealGameSyncLauncher to download the latest update.

Note: You may need to remove UnrealGameSync from your startup applications before restarting, deleting the folder, re-add UGS to the startup applications, and restart from there depending on how you set up UGS.

Case 2: If a user either doesn’t have the proper connection, or the proper permissions to see the Perforce path where the UGS updated binaries are, UGS can hang indefinitely, not allowing the user to proceed. If this is the case, either update the “Depot Path” in the connection settings, or speak with your Perforce admin to get the correct access to the files.

Random Build Errors related to “can’t find files”
This is usually a Perforce related error, and not necessarily UGS-related. If your workspace has got issues, first try force syncing the entire engine directory, and if all else fails, create a new workspace.

This can also happen when Sync Filters aren’t configured properly, either with something important for building getting filtered out ( IE: Win64 folders ), or a dependency to a file that’s covered by a sync filter has been introduced accidentally. The guide for configuring sync filters is here: UGS Sync Filter Setup

Cooking from a UGS Copy of the Editor fails
If you’re getting an error similar to:

ERROR: Failed to find command BuildCookRun

When attempting to cook or package from a precompiled binary version of the engine distributed through UGS, it could be due to needing the source folder for this operation.

We’re looking to improve this, but currently even if you’re not actually building the source code, you’ll need the source directory for cooking and packaging through the precompiled binaries used by UGS. If this is part of your workflow, check your sync filters to make sure you’re not excluding the source directory, even if you’re not working directly with it.

Compiler limit: internal heap limit reached
If you encounter an error similar to the following when compiling:

Fatal Error C1060: Compiler is out of Heap Space

Fatal Error C1076: compiler limit: internal heap limit reached; use /Zm to specify a higher limit

Error C3859: virtual memory range for PCH exceeded; please recompile with a command line option of ‘-Zm123’ or greater

Short-Term Workaround
Restart your machine as this clears cached memory and can temporarily unblock a compile.

Long-term Resolution
You should contact your IT department with a description of your problem. In some cases, increasing the maximum page file size through the Control Panel may help, but this is something that would need to be done through IT at most studios.

(Windows) Nothing happens when launching the game or editor, or the editor crashes right away with a weird error
Most of the time this occurs on a machine that hasn’t been configured to run Unreal before. If you’re on a new machine, have everything synced, and everything else seems to be in working order, but nothing happens when launching, try running the UE4PrereqSetup_x64.exe application located at:

/Engine/Extras/Redist/en-us.

This should install the prerequisites needed to run Unreal on a machine that has not done so previously.

UGS Crashes on Launch
UnrealGameSync uses P4 Command Line tools to query Perforce for updates. Not having Command Line tools installed is the most common cause of a crash on Launch.

Resolution:

  1. Rerun the Perforce Client Installer
  2. During installation, ensure command line tools are included

Check for P4 Command Line tools

  1. Open a Command window
  2. Enter p4.
  3. Press Enter.
  4. If P4 Command Line tools are installed, a series of help commands are printed
  5. If P4 Command Line tools are not installed, the error File not found is printed

Generate Project Files Errors
When generating project files, if you encounter an error similar to:

Setting up Unreal Engine 4 project files…
UnrealBuildTool Exception: System.FormatException: Index (zero based) must be greater than or equal to zero and less than the size of the argument list.
at System.Text.StringBuilder.AppendFormatHelper(IFormatProvider provider, String format, ParamsArray args)
at System.String.FormatHelper(IFormatProvider provider, String format, ParamsArray args)
at System.String.Format(String format, Object[] args)

ERROR: UnrealBuildTool was unable to generate project files. Press any key to continue . . . Failed to generate project files (exit code 1).

This is typically caused by missing Visual Studio Components.

Ensure all Visual Studio Components are installed according to: Setting Up Visual Studio for Unreal Engine | Unreal Engine Documentation

If you encounter an error similar to:

error MSB3644: The reference assemblies for framework “.NETFramework,Version=v4.6.2” were not found.

Install the SDK and Developer Pack from https://www.microsoft.com/en-us/download/details.aspx?id=53321

Error: System.ComponentModel.Win32Exception
When building using UGS, if the following error appears:

ubt> Using Visual Studio 2017 14.16.27023 toolchain (C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Tools\MSVC\14.16.27023) and Windows 10.0.17763.0 SDK (C:\Program Files (x86)\Windows Kits\10).

ubt> ERROR: System.ComponentModel.Win32Exception (0x80004005): The system cannot find the file specified

This is caused when we install the .NET Framework and other developer packages, and try to sync before restarting the computer.

To fix, restart the computer, generate project files again, and rebuild.

Error: System.UnauthorizedAccessException
This occurs typically with versions of UGS that haven’t been updated in some time and look like:

UnrealGameSync has crashed.
System.UnauthorizedAccessException: Access to the path is denied.

Resolution:

  • Navigate to C:<user>\AppData\Local\UnrealGameSync
  • Delete UnrealGameSync.ini
    • Warning - removing this file will remove user data, including
      • Saved build configurations
      • Editor command line arguments
      • Favorited open projects
      • Precompiled editor and incremental build elections

Couldn’t find any Perforce workspace containing …/.uproject. Check your connection settings.
If you’re setting up UGS for the first time and add a project using the local file dialog, but still get the above error:

  • Try adding the same file through the Open Project → Workspace → New… dialog.
  • If you’re not able to, this is a Perforce permissions issue and you’ll need to work with your Perforce administrator to make sure you have the correct access permissions for the stream and files that your workspace targets.

Connection to Server Failure
Attempting to connect to your Perforce server with an unrecognized port number will return the following error:

Perforce client error: Connect to server failed; check $P4PORT

To fix this:

  • Open a command/terminal window
  • Enter p4 set P4PORT=
  • Press Enter
  • Close and relaunch UGS

Likewise, connecting with an unknown user will generate the error:

Access for user ‘USERNAME’ has not been enabled by ‘p4 protect’

To fix this, open a command window and:

  • Enter p4 set P4USER=<perforce.username>
  • Press Enter
  • Close and relaunch UGS

System.Io.FileNotFoundException: Ionic.Zip.Reduced

  • Verify that C:\Users[User.name]\AppData\Local\UnrealGameSync\Latest contains Ionic.Zip.Reduced.dll
    • If it does exist, you are likely missing a file from the workspace and should force sync the Engine\Binaries folder in your workspace
  • Otherwise, check that your Anti-virus is not quarantining it. Follow the steps for your anti-virus to “trust” the file
  • If you’re unsure how to do that, terminate UGS from the taskmanager
  • Delete the contents of C:\Users[User.name]\AppData\Local\UnrealGameSync\Latest
  • Restart UGS
  • Confirm after UGS opens that the file exists now.

UGS is not using the correct proxy server
If after opening the Diagnostics menu ( bottom right corner of main window, Options → Diagnostics at the very bottom of the list ), the diagnostics menu reads that you’re using your proxy server but syncing is still failing:

  • Open a new project in UGS
  • Look for “Using default Perforce server settings”
  • Click on “Change” [See Screenshot item 3]
  • Uncheck the box that says “Use default connection settings” [See Screenshot item 4]
  • Enter your proxy server and user name in the provided fields [See Screenshot item 5]
  • Click Ok
  • Opening the UGS diagnostic should now show the correct server settings.

UGS-ServerSettings.png

UE VERSION