core.EnsuresAreErrors

core.EnsuresAreErrors

#Overview

name: core.EnsuresAreErrors

This variable is created as a Console Variable (cvar).

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of core.EnsuresAreErrors is to control how failed ensure conditions are logged in Unreal Engine 5. It determines whether these failures are treated as errors or warnings in the logging system.

This setting variable is primarily used in the Core module of Unreal Engine, specifically in the assertion and debugging subsystem. It’s referenced in the AssertionMacros.cpp file, which is part of the core error handling and debugging infrastructure.

The value of this variable is set through the FAutoConsoleVariableRef system, which allows it to be modified at runtime via console commands. By default, it’s set to 1 (true), meaning failed ensures are logged as errors.

The associated variable GEnsuresAreErrors directly interacts with core.EnsuresAreErrors. They share the same value, with GEnsuresAreErrors being the actual int32 variable used in the C++ code to check the setting’s value.

Developers must be aware that changing this variable can significantly impact the behavior of the engine’s error reporting system. When set to true (1), failed ensures will be logged as errors, which may cause certain processes like cooking to fail. When set to false (0), they will be logged as warnings, which are less severe and won’t cause process failures.

Best practices for using this variable include:

  1. Keep it set to true (1) during development to catch and address issues early.
  2. Consider setting it to false (0) in shipping builds if you want to prevent ensure failures from being treated as critical errors.
  3. Use it in conjunction with other debugging tools and practices to maintain code quality and stability.

Regarding the associated variable GEnsuresAreErrors:

The purpose of GEnsuresAreErrors is to serve as the actual int32 variable that the C++ code checks to determine how to handle ensure failures.

It’s used directly in the Core module’s error handling system, specifically in the FDebug::EnsureFailed function.

The value of GEnsuresAreErrors is set by the core.EnsuresAreErrors console variable through the FAutoConsoleVariableRef system.

This variable interacts closely with the logging system, determining whether to use UE_LOG with Error or Warning verbosity levels when an ensure fails.

Developers should be aware that modifying GEnsuresAreErrors directly in code is not recommended. Instead, they should use the core.EnsuresAreErrors console variable to change its value.

Best practices for GEnsuresAreErrors include:

  1. Treat it as read-only in most code scenarios.
  2. Use it to conditionally handle ensure failures in performance-critical code sections if necessary.
  3. Consider its value when implementing custom error handling or logging systems that interact with Unreal’s ensure mechanism.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/AssertionMacros.cpp:107

Scope: file

Source code excerpt:

int32 GEnsuresAreErrors = 1;
FAutoConsoleVariableRef CVarEnsuresAreErrors(
	TEXT("core.EnsuresAreErrors"),
	GEnsuresAreErrors,
	TEXT("True means failed ensures are logged as errors. False means they are logged as warnings."),
	ECVF_Default);

bool GEnsureAlwaysEnabled = true;
FAutoConsoleVariableRef CVarEnsureAlwaysEnabled(

#Associated Variable and Callsites

This variable is associated with another variable named GEnsuresAreErrors. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/AssertionMacros.cpp:105

Scope: file

Source code excerpt:

 * Errors will fail certain processes like cooks, whereas warnings will not.
 */
int32 GEnsuresAreErrors = 1;
FAutoConsoleVariableRef CVarEnsuresAreErrors(
	TEXT("core.EnsuresAreErrors"),
	GEnsuresAreErrors,
	TEXT("True means failed ensures are logged as errors. False means they are logged as warnings."),
	ECVF_Default);

bool GEnsureAlwaysEnabled = true;
FAutoConsoleVariableRef CVarEnsureAlwaysEnabled(
	TEXT("core.EnsureAlwaysEnabled"),

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/AssertionMacros.cpp:429

Scope (from outer to inner):

file
function     FORCENOINLINE void FDebug::EnsureFailed

Source code excerpt:

	{
#if !NO_LOGGING
		if (GEnsuresAreErrors)
		{
			UE_LOG(LogOutputDevice, Error, TEXT("Ensure condition failed: %hs" FILE_LINE_DESC_ANSI "\n%s\n"), Expr, File, Line, Msg);
		}
		else
		{
			UE_LOG(LogOutputDevice, Warning, TEXT("Ensure condition failed: %hs" FILE_LINE_DESC_ANSI "\n%s\n"), Expr, File, Line, Msg);

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/AssertionMacros.cpp:475

Scope (from outer to inner):

file
function     FORCENOINLINE void FDebug::EnsureFailed

Source code excerpt:

			// Dump the error and flush the log.
#if !NO_LOGGING
			FDebug::LogFormattedMessageWithCallstack(LogOutputDevice.GetCategoryName(), __FILE__, __LINE__, TEXT("=== Handled ensure: ==="), ErrorMsg, (GEnsuresAreErrors ? ELogVerbosity::Error : ELogVerbosity::Warning));
#endif
			GLog->Flush();

			// Trace the error
#if !NO_LOGGING
			if (GEnsuresAreErrors)
			{
				TRACE_LOG_MESSAGE(LogOutputDevice, Error, TEXT("%s"), ErrorMsg);
			}
			else
			{
				TRACE_LOG_MESSAGE(LogOutputDevice, Warning, TEXT("%s"), ErrorMsg);

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Misc/AssertionMacros.cpp:547

Scope (from outer to inner):

file
function     FORCENOINLINE void FDebug::EnsureFailed

Source code excerpt:

			// Add message to log even without stacktrace. It is useful for testing fail on ensure.
#if !NO_LOGGING
			if (GEnsuresAreErrors)
			{
				UE_LOG(LogOutputDevice, Error, TEXT("Ensure condition failed: %hs " FILE_LINE_DESC_ANSI), Expr, File, Line);
			}
			else
			{
				UE_LOG(LogOutputDevice, Warning, TEXT("Ensure condition failed: %hs " FILE_LINE_DESC_ANSI), Expr, File, Line);