Using sanitizers

What are sanitizers?

Sanitizers are static instrumentation tools that help find bugs that traditional debuggers usually cannot catch. This is particularly useful when combined with Unit testing in continuous integration.

Sanitizers can be used on Windows, macOS and Linux by using the Clang (LLVM), GCC or Visual Studio compilers. Certain platforms may also have their own sanitizers available. In situations where a single sanitizer is provided by several different compilers, remember that their output and behavior will differ slightly.

Using sanitizers on Godot

Sanitizers require recompiling the binary. This means you cannot use official Godot binaries to run sanitizers.

When compiling with any of the sanitizers enabled, the resulting binary will have the .san suffix added to its name to distinguish it from a binary without sanitizers.

There is a performance impact as many additional runtime checks need to be performed. Memory utilization will also increase. It is possible to enable certain combinations of multiple sanitizers in a single build. Beware of the performance impact when using multiple sanitizers at once though, as the resulting binary may be excessively slow.

Certain options can be passed to sanitizers without having to recompile the binary using environment variables.

Address sanitizer (ASAN)

The address sanitizer is generally the most frequently used sanitizer. It can diagnose issues such as buffer overruns and out-of-bounds access. If the engine crashes with a message such as free(): invalid pointer, this is typically the result of a buffer overrun. (This message is printed by the C runtime, not Godot.)

In certain situations (such as detecting uninitialized memory reads), the address sanitizer doesn't suffice. The Memory sanitizer (MSAN) should be used instead.

It is also possible to detect use-after-return situations by specifying the ASAN_OPTIONS=detect_stack_use_after_return=1 environment variable before running Godot (not when compiling it). This increases the address sanitizer's runtime overhead, so only enable this feature when you actually need it.

To enable the address sanitizer in a Godot build, pass the use_asan=yes SCons option when compiling. Enabling ASAN generally makes the resulting binary about 2× slower.

Warning

Due to a design decision, the address, memory and thread sanitizers are mutually exclusive. This means you can only use one of those sanitizers in a given binary.

Leak sanitizer (LSAN)

The leak sanitizer can detect memory leaks, which are situations where memory that is no longer in use is never freed by the running program. This can potentially lead to out-of-memory situations if the program runs for long enough. Since Godot may run on dedicated servers for months or even years without a restart, it's important to fix memory leaks when they occur.

To enable the leak sanitizer in a Godot build, pass the use_lsan=yes SCons option when compiling. Enabling LSAN only has a small performance overhead, but the program will be much slower to exit as leak detection occurs when the program exits.

Memory sanitizer (MSAN)

The memory sanitizer complements the Address sanitizer (ASAN). Unlike the address sanitizer, the memory sanitizer can detect uninitialized memory reads.

To enable the memory sanitizer in a Godot build, pass the use_msan=yes SCons option when compiling. Enabling MSAN generally makes the resulting binary about 3× slower.

Warning

Due to a design decision, the address, memory and thread sanitizers are mutually exclusive. This means you can only use one of those sanitizers in a given binary.

Thread sanitizer (TSAN)

The thread sanitizer is used to track down race conditions related to multithreading. A race condition is when multiple threads try to modify the same data at the same time. Since thread scheduling can be ordered in any fashion by the operating system, this leads to incorrect behavior that only occurs occasionally (and can be difficult to track as a result). To prevent a race condition, you need to add a lock to ensure only one thread can access the shared data at a given time.

To enable the thread sanitizer in a Godot build, pass the use_tsan=yes SCons option when compiling. Enabling TSAN generally makes the resulting binary 10× slower, while also multiplying memory usage by an approximately 8× factor.

Warning

Due to a design decision, the address, memory and thread sanitizers are mutually exclusive. This means you can only use one of those sanitizers in a given binary.

Note

On Linux, if you stumble upon the following error:

FATAL: ThreadSanitizer: unexpected memory mapping

You may need to temporarily lower the Address Space Layout Randomization (ASLR) entropy in your system with:

sudo sysctl vm.mmap_rnd_bits=28

Or preferably disable it entirely with:

sudo sysctl kernel.randomize_va_space=0

And as soon as you are done with the thread sanitizer, increase the ASLR entropy with:

sudo sysctl vm.mmap_rnd_bits=32

Or re-enable ASLR with:

sudo sysctl kernel.randomize_va_space=2

Rebooting your machine will also revert the ASLR state to its default values.

It's important to revert the changes as soon as possible because lowering the ASLR entropy or disabling ASLR entirely can be a security risk.

Undefined behavior sanitizer (UBSAN)

The undefined behavior sanitizer is used to track down situations where the program exhibits random and unpredictable behavior. This is due to C/C++ code that is accepted by the compiler, but is not correct. Compiling with a different set of optimizations can also change the observed results of undefined behavior.

To enable the undefined behavior sanitizer in a Godot build, pass the use_ubsan=yes SCons option when compiling. Enabling UBSAN only has a small performance overhead.

Platform-specific sanitizers

Web

When compiling for the Web, there are 2 additional sanitizer SCons options available:

  • use_assertions=yes enables runtime Emscripten assertions, which can catch various issues.

  • use_safe_heap=yes enables Emscripten's SAFE_HEAP sanitizer. It provides similar functionality to ASAN, but it focuses on issues that are specific to WebAssembly. SAFE_HEAP is not guaranteed to be compatible with ASAN and UBSAN in the same binary, so you may have to build it separately.

User-contributed notes

Please read the User-contributed notes policy before submitting a comment.