Unity 6
Crash Debugging
Firebase Crashlytics
Android ANR
IL2CPP
Mobile Game Development
Game Engineering

Unity 6 Crash Analytics & Debugging Guide: Crashlytics, Android ANRs & IL2CPP Symbolication

13 min read
Eshan Naithani

In mobile and cross-platform Unity development, runtime stability directly governs store visibility and player retention. Google Play's Android Vitals and the Apple App Store penalize titles that exceed store-defined bad-behavior thresholds for crash rate and Application Not Responding (ANR) rate—suppressing organic store featuring long before players leave 1-star reviews.

However, debugging crashes in a production Unity 6 IL2CPP build is very different from fixing a NullReferenceException in the Unity Editor Console. Once your C# code is cross-compiled into native ARM64 machine code (libil2cpp.so on Android or the Mach-O binary on iOS), raw crash logs arrive as stripped hexadecimal memory offsets, multi-threaded deadlocks disguise themselves as Android UnityPlayer.pause ANRs, and Out-Of-Memory (OOM) kills terminate the app without firing C# callbacks.

This engineering guide covers end-to-end crash analytics and debugging in Unity 6: distinguishing managed exceptions from native crashes, integrating Firebase Crashlytics and Unity Cloud Diagnostics, symbolicating IL2CPP stack traces, diagnosing Android ANRs, wiring GameAnalytics Error Events, and validating your pipeline with reproducible crash tests.

Experiencing crashes, OOM kills, or ANR spikes in a live Unity project? Pair this guide with our Unity 6 Mobile Game Optimization Guide and Unity Mobile Memory Profiling Guide, or explore our Unity Game Development Services.


1. Native Crashes vs. Managed C# Exceptions vs. Android ANRs vs. OOM Kills

Before selecting a diagnostic tool, classify which failure mode you are dealing with. Each originates in a different layer of the runtime stack and requires a different capture mechanism:

Failure TypeWhere It OriginatesProcess Terminates?How It Appears in LogsPrimary Diagnostic Tools
Managed C# ExceptionC# scripts compiled via IL2CPP/Mono (NullReferenceException, KeyNotFoundException, MissingReferenceException)Usually No (aborts current C# call stack; game often continues in a corrupted state)Readable C# class/method stack trace via Application.logMessageReceivedFirebase Crashlytics (Non-Fatals), Unity Cloud Diagnostics, GameAnalytics Error Events
Native Engine / Plugin CrashC++ engine (libunity.so), IL2CPP runtime (libil2cpp.so), GPU driver (libGLES_mali.so), or native .so/.a SDKsYes (Immediate) via OS signals (SIGSEGV, SIGABRT, SIGILL, EXC_BAD_ACCESS)Raw memory addresses unless symbolicated with .symbols.zip / .dSYMFirebase Crashlytics NDK, Google Play Android Vitals, Xcode Organizer, Backtrace, Sentry
Android ANR (Application Not Responding)Android OS Watchdog when the Java main thread fails to respond to input or broadcast events within the OS timeoutYes / User Prompted (SIGQUIT thread dump generated)Multi-thread dump showing main waiting on UnityMain (or vice versa)Google Play Console Android Vitals, Firebase Crashlytics (ANR reporting), Android Studio Profiler
Out-Of-Memory (OOM) TerminationOS kernel memory watchdog (Android lmkd or iOS Jetsam) killing the process when physical RAM is exhaustedYes (Instant SIGKILL) — in-process handlers often cannot run before deathForeground/background exit without a C# stack trace; EXIT_REASON_LOW_MEMORY on Android 11+Unity Memory Profiler, Addressables Profiler, Xcode Memory Gauge, Android ApplicationExitInfo

2. Setting Up Firebase Crashlytics in Unity 6 (C# Breadcrumbs & Custom Keys)

Firebase Crashlytics for Unity is the most widely deployed crash reporter for Android and iOS Unity games because it captures both native NDK/iOS crashes and non-fatal C# exceptions, while letting you attach custom key-value state and breadcrumb logs leading up to a crash.

Why Breadcrumbs and Custom Keys Are Essential

A stack trace telling you that BranchController.CanAcceptBird() threw an exception on line 84 only tells you where the crash happened—not which level configuration or which UI popup put the game into that state. By logging breadcrumbs (Crashlytics.Log) and low-cardinality state keys (Crashlytics.SetCustomKey), every crash report includes the exact scene, level number, memory tier, and last player action.

Verified C# Implementation (CrashTelemetryBootstrapper.cs)

CSHARP
using System;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.SceneManagement;
#if FIREBASE_CRASHLYTICS_ENABLED
using Firebase;
using Firebase.Crashlytics;
#endif

namespace MyGame.Diagnostics
{
    public sealed class CrashTelemetryBootstrapper : MonoBehaviour
    {
        public static bool IsReady { get; private set; }

        private async void Awake()
        {
            DontDestroyOnLoad(gameObject);
            await InitializeCrashlyticsAsync();
        }

        private async Task InitializeCrashlyticsAsync()
        {
#if FIREBASE_CRASHLYTICS_ENABLED
            DependencyStatus status = await FirebaseApp.CheckAndFixDependenciesAsync();
            if (status != DependencyStatus.Available)
            {
                Debug.LogError($"[Crashlytics] Could not resolve Firebase dependencies: {status}");
                return;
            }

            // Treat uncaught C# exceptions according to project policy (false = report as non-fatal)
            Crashlytics.ReportUncaughtExceptionsAsFatal = false;

            // Attach baseline hardware & build context keys
            Crashlytics.SetCustomKey("build_version", Application.version);
            Crashlytics.SetCustomKey("unity_version", Application.unityVersion);
            Crashlytics.SetCustomKey("system_ram_mb", SystemInfo.systemMemorySize.ToString());
            Crashlytics.SetCustomKey("graphics_api", SystemInfo.graphicsDeviceType.ToString());
            Crashlytics.SetCustomKey("active_scene", SceneManager.GetActiveScene().name);

            SceneManager.activeSceneChanged += OnActiveSceneChanged;
            IsReady = true;
            Debug.Log("[Crashlytics] Initialized successfully.");
#else
            await Task.CompletedTask;
#endif
        }

        private void OnDestroy()
        {
            SceneManager.activeSceneChanged -= OnActiveSceneChanged;
        }

        private static void OnActiveSceneChanged(Scene previousScene, Scene newScene)
        {
            SetContextKey("active_scene", newScene.name);
            RecordBreadcrumb($"Scene transition: {previousScene.name} -> {newScene.name}");
        }

        public static void SetContextKey(string key, string value)
        {
#if FIREBASE_CRASHLYTICS_ENABLED
            if (!IsReady) return;
            Crashlytics.SetCustomKey(key, value ?? "null");
#endif
        }

        public static void RecordBreadcrumb(string message)
        {
#if FIREBASE_CRASHLYTICS_ENABLED
            if (!IsReady) return;
            Crashlytics.Log($"[{Time.realtimeSinceStartup:F1}s] {message}");
#endif
        }

        public static void ReportHandledException(Exception exception, string contextNote = null)
        {
            if (exception == null) return;

            if (!string.IsNullOrEmpty(contextNote))
            {
                RecordBreadcrumb($"HandledException Context: {contextNote}");
            }

#if FIREBASE_CRASHLYTICS_ENABLED
            if (IsReady)
            {
                Crashlytics.LogException(exception);
            }
#endif
            Debug.LogException(exception);
        }
    }
}

3. IL2CPP Symbolication: Turning Hex Offsets into Readable Stack Traces

When Unity builds your game with the IL2CPP scripting backend, it translates CIL bytecode into C++ and compiles it with the Android NDK (clang++) or Xcode LLVM toolchain into stripped machine binaries (libil2cpp.so on Android, UnityFramework on iOS). Stripping removes symbol tables from the shipping APK/AAB/IPA so the player download stays small.

Without symbol files, a native crash log looks like this:

TEXT
signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x0000000000000018
backtrace:
  #00 pc 00000000009f4c18  /data/app/.../lib/arm64/libil2cpp.so (BuildId: 8a9b7c6d...)
  #01 pc 00000000009f5104  /data/app/.../lib/arm64/libil2cpp.so (BuildId: 8a9b7c6d...)
  #02 pc 000000000051a890  /data/app/.../lib/arm64/libunity.so (BuildId: 3f2e1d0c...)

Step 1: Generating .symbols.zip in Unity 6 (Android)

  1. Open File > Build Profiles (or Project Settings > Player > Android > Publishing Settings).
  2. Locate Debug Symbols (or Create symbols.zip in earlier Unity versions):
    • Select Public for standard release builds (produces a compact symbol package containing function names), or Full when you need exact C++ line numbers and DWARF debug tables.
  3. Build your Android App Bundle (.aab). Unity outputs both Game.aab and Game-1.0.0-v12.symbols.zip in your build folder (and embeds configurable symbols inside the .aab depending on your Gradle configuration).

Step 2: Uploading Symbols to Google Play Console & Firebase Crashlytics

  • Google Play Console: In App Bundle Explorer, select your release version, switch to the Downloads tab, and verify or upload the Native debug symbols (.zip) file.
  • Firebase CLI: Upload the generated .symbols.zip during your CI/CD build step so Crashlytics symbolicates both libunity.so and libil2cpp.so:
    BASH
    firebase crashlytics:symbols:upload --app=1:1234567890:android:abcdef123456 build/Android/Game-1.0.0-v12.symbols.zip
    
  • iOS (.dSYM): In Xcode (Organizer > Archives or Build Settings > Debug Information Format = DWARF with dSYM File), upload the generated .dSYM bundle to Crashlytics via the upload-symbols script included in the Firebase iOS SDK pods.

Step 3: Local CLI Symbolication with Android NDK llvm-addr2line

If QA sends you a raw adb logcat tombstone from a local test device, you can symbolicate any libil2cpp.so program counter (pc) offset directly on your development machine using llvm-addr2line inside the Android NDK folder bundled with Unity Hub:

BASH
# Locate llvm-addr2line inside your Unity Editor Android NDK installation
# Extract libil2cpp.sym.so from your matching .symbols.zip (arm64-v8a)
llvm-addr2line -f -C -i -e ./symbols/arm64-v8a/libil2cpp.sym.so 00000000009f4c18

[!IMPORTANT] BuildId Matching Rule: Every IL2CPP compilation produces a unique GNU BuildId hash. You cannot symbolicate a crash from build v12 using the .symbols.zip generated by a later rebuild (v13), even if no C# code changed. Archive the .symbols.zip and .dSYM artifact alongside every release build in your CI/CD pipeline.


4. Debugging Android ANRs (Application Not Responding) in Unity

An Android ANR occurs when the Android OS detects that your application's main UI thread (main) has been unresponsive to user input or system broadcasts (such as onPause, onStop, or focus changes) for several seconds.

How to Read a Unity ANR Stack Trace (The UnityPlayer.pause Trap)

In Google Play Console's Android Vitals, the most common Unity ANR headline looks like this:

TEXT
"main" tid=1 Native
  #00 pc 0000000000089ab4  /apex/com.android.runtime/lib64/bionic/libc.so (syscall+28)
  at java.util.concurrent.Semaphore.tryAcquire(Semaphore.java:502)
  at com.unity3d.player.UnityPlayer.pauseUnity(Unknown Source)
  at com.unity3d.player.UnityPlayer.pause(Unknown Source)

Why this happens:

  1. On Android, Java UI events and Activity lifecycle callbacks (onPause) run on the main (TID 1) thread, whereas the Unity engine loop (Update, LateUpdate, rendering, C# scripts) runs on a separate thread named UnityMain.
  2. When the player locks their screen, switches apps, or opens a full-screen rewarded video ad, the Android main thread calls UnityPlayer.pause() and waits on a Semaphore for UnityMain to finish its current frame.
  3. If UnityMain is frozen—for example, executing synchronous File.WriteAllText() inside OnApplicationPause(true), compiling a complex shader variant, synchronously deserializing a large asset, or waiting on a lock held by an ad SDK callback—the main thread's semaphore wait times out and Android triggers an ANR.

Actionable Fixes for Unity Android ANRs

  1. Always Scroll Down to the UnityMain Thread in the ANR Dump: Never stop reading at main (tid=1). Search the ANR trace for "UnityMain" to see the exact C# or native function stalling the engine loop.
  2. Keep OnApplicationPause(bool pauseStatus) Lightweight: Players frequently background mobile games. Do not serialize megabytes of JSON or make blocking HTTP calls synchronously inside OnApplicationPause(true). Maintain an incremental dirty-state buffer and write small payloads asynchronously.
  3. Replace Synchronous Asset Loads with Async Addressables: Loading large prefabs or scenes synchronously stalls UnityMain. Stream assets asynchronously via Unity Addressables (LoadAssetAsync).
  4. Dispatch Third-Party SDK Callbacks onto the Main Thread Safely: Many Android Java/Kotlin ad mediation and billing plugins invoke callbacks on background binder threads. Touching Unity APIs (GameObject.SetActive, SceneManager, PlayerPrefs) directly from a background thread causes race conditions, native crashes, or deadlocks.

5. Bridging Unity Cloud Diagnostics & GameAnalytics Error Events

While Firebase Crashlytics handles deep stack-trace symbolication, combining it with Unity Cloud Diagnostics and GameAnalytics Error Events gives you two complementary views:

  1. Unity CrashReportHandler Metadata (UnityEngine.CrashReportHandler): If you use Unity Cloud Diagnostics (Backtrace integration), attach runtime metadata via CrashReportHandler.SetUserMetadata("level_id", currentLevel) so Unity Editor-integrated reports carry custom state.
  2. GameAnalytics Error Events (GameAnalytics.NewErrorEvent): Connecting Unity's Application.logMessageReceived callback (with deduplication/rate-limiting so a NullReferenceException inside Update() does not flood HTTP queues) to GameAnalytics.NewErrorEvent allows product managers to correlate error rates directly against D1/D7 retention and level progression drop-off funnels.
CSHARP
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.CrashReportHandler;
using GameAnalyticsSDK;

namespace MyGame.Diagnostics
{
    public sealed class RuntimeExceptionForwarder : MonoBehaviour
    {
        private const int MaxUniqueErrorsPerSession = 15;
        private readonly HashSet<int> _reportedErrorHashes = new HashSet<int>();

        private void OnEnable()
        {
            Application.logMessageReceived += HandleUnityLog;
        }

        private void OnDisable()
        {
            Application.logMessageReceived -= HandleUnityLog;
        }

        public static void SetActiveGameplayMetadata(string levelKey)
        {
#if !UNITY_EDITOR
            CrashReportHandler.SetUserMetadata("active_level", levelKey);
#endif
            CrashTelemetryBootstrapper.SetContextKey("active_level", levelKey);
        }

        private void HandleUnityLog(string condition, string stackTrace, LogType type)
        {
            if (type != LogType.Exception && type != LogType.Error) return;
            if (_reportedErrorHashes.Count >= MaxUniqueErrorsPerSession) return;

            string combined = $"{type}: {condition}\n{stackTrace}";
            int hash = combined.GetHashCode();

            // Deduplicate identical per-frame Update() exceptions within the same session
            if (!_reportedErrorHashes.Add(hash)) return;

            GAErrorSeverity severity = (type == LogType.Exception)
                ? GAErrorSeverity.Critical
                : GAErrorSeverity.Error;

            GameAnalytics.NewErrorEvent(severity, combined);
        }
    }
}

6. Reproducible Crash Testing Before Release (Utils.ForceCrash)

Never ship to production assuming your symbol upload pipeline works—verify it in a staging build using Unity's official UnityEngine.Diagnostics.Utils.ForceCrash API.

CSHARP
using System;
using UnityEngine;
using UnityEngine.Diagnostics;

namespace MyGame.Diagnostics
{
    public sealed class StagingCrashVerifier : MonoBehaviour
    {
#if DEVELOPMENT_BUILD || UNITY_EDITOR
        public void TriggerTestManagedException()
        {
            CrashTelemetryBootstrapper.RecordBreadcrumb("QA triggered test managed exception");
            try
            {
                throw new InvalidOperationException("Staging QA Test: Verified Non-Fatal C# Exception");
            }
            catch (Exception ex)
            {
                CrashTelemetryBootstrapper.ReportHandledException(ex, "StagingCrashVerifier");
            }
        }

        public void TriggerTestNativeCrash()
        {
            CrashTelemetryBootstrapper.RecordBreadcrumb("QA triggered ForceCrash(AccessViolation)");
            Debug.LogWarning("[StagingCrashVerifier] Forcing native AccessViolation crash...");
            // Deterministically triggers a native crash to test symbolication (.symbols.zip / .dSYM)
            Utils.ForceCrash(ForcedCrashCategory.AccessViolation);
        }
#endif
    }
}

Pre-Launch Crash Verification Checklist

  • [ ] Generate Symbols Enabled: Debug Symbols set to Public or Full for Android IL2CPP builds and DWARF with dSYM File for iOS builds.
  • [ ] Symbol Archive Stored: .symbols.zip and .dSYM artifacts archived in CI/CD and uploaded to Google Play Console and Firebase Crashlytics.
  • [ ] Staging ForceCrash Verified: Triggered Utils.ForceCrash(ForcedCrashCategory.AccessViolation) on a physical test device, relaunched the app, and verified the crash report displays human-readable C# / C++ method names instead of raw .so memory offsets.
  • [ ] OnApplicationPause Audited: Confirmed zero blocking file I/O or synchronous asset loads occur during app backgrounding to prevent UnityPlayer.pause Android ANRs.

Frequently Asked Questions


Official Documentation References

Need help architecting or optimizing your Unity mobile game? Let's discuss your technical roadmap.

Share this article

Get Practical Unity Development Insights

Technical guides on Unity performance, AI gameplay systems, mobile monetization, and game development.

Unsubscribe at any time. Your data is never shared.

Recommended Reading

More articles in Unity 6