Understanding Stack Traces in Unity Crash Logs

This guide covers understanding stack traces in Unity crash logs in detail. Unity crash logs contain stack traces that point you directly to the source of a bug, but only if you know how to read them. Whether you are tracking down a NullReferenceException in a managed C# build or decoding a mangled IL2CPP crash on a player's device, understanding the anatomy of a Unity stack trace is essential for efficient debugging.

Anatomy of a Unity Stack Trace

When an unhandled exception occurs in Unity, the engine captures the call stack and prints it to the console or log file. A typical managed stack trace looks like this:

NullReferenceException: Object reference not set to an instance of an object
  at PlayerInventory.AddItem (Item item) [0x00023] in Assets/Scripts/PlayerInventory.cs:47
  at LootDrop.CollectLoot () [0x00014] in Assets/Scripts/LootDrop.cs:31
  at UnityEngine.Events.InvokableCall.Invoke () [0x00011]

The first line is the exception type and message. Each subsequent line is a stack frame. The topmost frame is where the exception was thrown. The hexadecimal value in brackets is the IL offset within the method, and the file path and line number follow. Frames from UnityEngine internals typically lack file paths since you do not have the engine source code.

The NullReferenceException Problem

NullReferenceException is the most common crash in Unity projects. It means you accessed a property or called a method on a reference that was null. The stack trace tells you exactly where it happened, but not which reference was null. Consider this code:

public void AddItem(Item item) {
    // If _inventory is null OR item is null, this line throws
    _inventory.items.Add(item.Clone());
}

Three different references on that single line could be null: _inventory, _inventory.items, or item. The stack trace only gives you line 47. To narrow it down, split chained calls across multiple lines during debugging, or add null checks that log which reference failed. In development builds, Unity's managed debugger can also break on the exception and show you the locals.

Managed vs. Native Stack Traces

Unity games can crash in two fundamentally different ways. A managed crash is an unhandled C# exception. These produce clean stack traces with method names and line numbers. You can catch them, log them, and often recover from them.

A native crash occurs in the Unity engine itself, in a native plugin, or in IL2CPP-compiled code. These produce platform-specific crash dumps with memory addresses instead of C# method names. On Windows you get a minidump. On Android you get a tombstone. On iOS you get a .crash file. Without debug symbols, native crash traces look like this:

# Native crash - no symbols loaded
0x00000001048a3c2f  GameAssembly.dylib + 4275247
0x00000001048872a4  GameAssembly.dylib + 4157092
0x0000000104910d88  GameAssembly.dylib + 4722056

The GameAssembly.dylib (or GameAssembly.dll on Windows) is the compiled output of IL2CPP. Every C# method in your project lives inside this single native binary, and without symbols, all you see are raw offsets.

Decoding IL2CPP Stack Traces

IL2CPP is Unity's default scripting backend for iOS, consoles, and most release builds. It converts C# intermediate language to C++ source code, then compiles that to native machine code. This conversion mangles method names. A C# method like PlayerInventory.AddItem(Item) becomes something like:

PlayerInventory_AddItem_m3F2A7B1C (PlayerInventory_t* __this, Item_t* ___item, ...)

To translate these back to readable C# names, you need the metadata files generated during the build. Unity outputs a LineNumberMappings.json and a MethodMap.tsv in the IL2CPP output directory. The MethodMap.tsv file maps mangled C++ function names back to their original C# signatures.

For line-level accuracy, use the --emit-source-mapping IL2CPP flag or keep the generated C++ source files. Each generated C++ file contains comments that reference the original C# file and line number.

Getting Line Numbers in Release Builds

By default, Mono release builds include method names but strip line numbers. To preserve line numbers, you need to ship the .pdb or .mdb debug symbol files alongside your managed assemblies. In the Unity Player Settings, set Managed Stripping Level to Low or Minimal to avoid having methods removed entirely by the linker.

For IL2CPP builds, line numbers require the symbol files for the native binary. On iOS, this is a dSYM bundle. On Android, these are the unstripped .so files in the symbols.zip that Unity generates at build time. Archive these files for every build you distribute, and you can symbolicate crash reports after the fact.

"A stack trace without line numbers is a treasure map without distances. You know the path, but you have to guess how far along it you are."

Practical Tips for Unity Stack Trace Debugging

Enable Application.logMessageReceived in your game to capture exceptions at runtime and forward them to your crash reporting system. Use StackTraceLogType.ScriptOnly for managed exceptions to reduce noise from engine internals. For IL2CPP builds, always archive the symbols.zip from your build output and upload it to your crash reporting tool so that native frames can be symbolicated automatically.

Bugnet's Unity SDK hooks into the log callback automatically and captures both managed and native stack traces with full symbolication support. When a player encounters a crash, the SDK collects the stack trace, attaches device metadata, and uploads it to your dashboard where it appears fully symbolicated and grouped by crash signature.

Related Issues

For a broader introduction to reading stack traces across game engines, see our beginner's guide to game stack traces. If you are specifically dealing with GetComponent returning null, check out fixing Unity NullReferenceException with GetComponent. To set up crash reporting in your project from scratch, read how to set up crash reporting for indie games.

Archive your IL2CPP symbol files on every build. The crash you cannot symbolicate is the crash you cannot fix.