PullErrorAdditionalMsg

PullErrorAdditionalMsg

#Overview

name: PullErrorAdditionalMsg

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of PullErrorAdditionalMsg is to provide an additional, customizable error message that is displayed when a payload pull operation fails in the Unreal Engine 5 virtualization system.

This setting variable is primarily used by the Virtualization module within Unreal Engine 5. It is specifically utilized in the FVirtualizationManager class, which is part of the UE::Virtualization namespace.

The value of this variable is set from a configuration file. This can be seen in the ApplySettingsFromConfigFiles function where it reads the value from a ConfigFile object:

ConfigFile.GetString(ConfigSection, TEXT("PullErrorAdditionalMsg"), PullErrorAdditionalMsg);

PullErrorAdditionalMsg interacts with the error handling system of the Virtualization module. It is used in conjunction with other error messages to provide more detailed information to the user when a payload pull fails.

Developers should be aware that this variable is only used when the error dialog is displayed to the user. It will have no effect if ‘UseLegacyErrorHandling’ is set to true.

Best practices for using this variable include:

  1. Keeping the message concise and informative.
  2. Using it to provide links to internal documentation or support resources.
  3. Ensuring the message is appropriate for all potential users who might see it.
  4. Regularly reviewing and updating the message to ensure it remains relevant and helpful.

It’s important to note that this variable allows for customization of error messages without needing to modify the source code, which can be particularly useful for teams with specific support processes or documentation.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1478, section: [Core.VirtualizationModule]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.cpp:1205

Scope (from outer to inner):

file
namespace    UE::Virtualization
function     void FVirtualizationManager::ApplySettingsFromConfigFiles

Source code excerpt:


	{
		ConfigFile.GetString(ConfigSection, TEXT("PullErrorAdditionalMsg"), PullErrorAdditionalMsg);
		// This value is not echoed to the log file, as seeing an error string there might confuse users
	}
	
	{
		ConfigFile.GetString(ConfigSection, TEXT("ConnectionHelpUrl"), ConnectionHelpUrl);
		// This value is not echoed to the log file

#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.cpp:2065

Scope (from outer to inner):

file
namespace    UE::Virtualization
function     FVirtualizationManager::ErrorHandlingResult FVirtualizationManager::OnPayloadPullError

Source code excerpt:

		}

		if (!PullErrorAdditionalMsg.IsEmpty())
		{
			MsgBuilder.AppendLine(FString(TEXT("")));
			MsgBuilder.AppendLine(PullErrorAdditionalMsg);
		}

		// By default we should quit the process unless the user can opt to retry
		EAppReturnType::Type Result = EAppReturnType::No;

		if (Utils::IsProcessInteractive())

#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.h:126

Scope: file

Source code excerpt:

 *												and when false a dialog will be displayed to the user warning them about the failed pull and 
 *												prompting them to retry the pull or to quit the process. [Default=true]
 * PullErrorAdditionalMsg [string]				An additional message that will be added to the error dialog presented on payload pull failure.
 *												This allows you to add custom information, such as links to internal help docs without editing
 *												code. Note that this additional message only works with the error dialog and will do nothing
 *												if 'UseLegacyErrorHandling' is true. [Default=""]
 * ForceCachingOnPull [bool]:					When true backends will be told to always upload the payload when a caching as a result of 
 *												a payload pull as in this scenario we already know that the backend failed to pull the payload
 *												before it was pulled from a backend later in the hierarchy. Can be used to try and skip
 *												expensive existence checks, or if a backend is in a bad state where it believes it has the payload
 *												but is unable to actually return the data. [Default=false]
 * UnattendedRetryCount [int32]:				How many times the process should retry pulling payloads after a failure is encountered if the
												process is unattended. Usually when a payload pull fails we ask the user to try and fix the issue
												and retry, but in unattended mode we just log an error and terminate the process. In some cases
												such as build machines with unreliable internet it is possible that the process could recover in
												which case setting this value might help. Zero or negative values will disable the system. 
												Note: If many pulls are occurring at the same time on many threads a very short network outage might
												spawn many errors in which case we try to group these errors into a single 'try' so 32 errors on 32
												threads would not immediately blow past a retry count of 30 for example. [Default=0]
 * UnattendedRetryTimer [int32]					If 'UnattendedRetryCount' is set to a positive value then this value sets how long (in seconds)
 *												the process should wait after a failure is encountered before retrying the pull. Depending on the
												likely cause of the failure you may want to set this value to several minutes. [Default=0]
 */

namespace UE::Virtualization
{
class FPullRequestCollection;

/** The default mode of filtering to use with package paths that do not match entries in UVirtualizationFilterSettings */
enum class EPackageFilterMode : uint8
{
	/** Packages will be virtualized by default and must be opted out by the use of UVirtualizationFilterSettings::ExcludePackagePaths */
	OptOut = 0,
	/** Packages will not be virtualized by default and must be opted in by the user of UVirtualizationFilterSettings::IncludePackagePaths */
	OptIn
};

/** Attempt to convert a string buffer to EPackageFilterMode */
bool LexTryParseString(EPackageFilterMode& OutValue, FStringView Buffer);

/** This is used as a wrapper around the various potential back end implementations. 
	The calling code shouldn't need to care about which back ends are actually in use. */
class FVirtualizationManager final : public IVirtualizationSystem
{
public:
	using FRegistedFactories = TMap<FName, IVirtualizationBackendFactory*>;
	using FBackendArray = TArray<IVirtualizationBackend*>;

	FVirtualizationManager();
	virtual ~FVirtualizationManager();

private:
	/* IVirtualizationSystem implementation */

	virtual bool Initialize(const FInitParams& InitParams) override;

	virtual bool IsEnabled() const override;
	virtual bool IsPushingEnabled(EStorageType StorageType) const override;

	virtual EPayloadFilterReason FilterPayload(const UObject* Owner) const override;

	virtual bool AllowSubmitIfVirtualizationFailed() const override;
	
	virtual bool PushData(TArrayView<FPushRequest> Requests, EStorageType StorageType) override;
	virtual bool PullData(TArrayView<FPullRequest> Requests) override;

	virtual EQueryResult QueryPayloadStatuses(TArrayView<const FIoHash> Ids, EStorageType StorageType, TArray<EPayloadStatus>& OutStatuses) override;

	virtual FVirtualizationResult TryVirtualizePackages(TConstArrayView<FString> PackagePaths, EVirtualizationOptions Options) override;

#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.h:341

Scope (from outer to inner):

file
namespace    UE::Virtualization
class        class FVirtualizationManager final : public IVirtualizationSystem

Source code excerpt:


	/** An additional error message to display when pulling payloads fails */
	FString PullErrorAdditionalMsg;

	/** Optional url used to augment connection failure error messages */
	static FString ConnectionHelpUrl;

	/** The number of times to retry pulling when errors are encountered in an unattended process, values <0 disable the system */
	int32 UnattendedRetryCount = 0;