Unity 6 Crash Analytics & Debugging Guide: Crashlytics, Android ANRs & IL2CPP Symbolication
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 Type | Where It Originates | Process Terminates? | How It Appears in Logs | Primary Diagnostic Tools |
|---|---|---|---|---|
| Managed C# Exception | C# 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.logMessageReceived | Firebase Crashlytics (Non-Fatals), Unity Cloud Diagnostics, GameAnalytics Error Events |
| Native Engine / Plugin Crash | C++ engine (libunity.so), IL2CPP runtime (libil2cpp.so), GPU driver (libGLES_mali.so), or native .so/.a SDKs | Yes (Immediate) via OS signals (SIGSEGV, SIGABRT, SIGILL, EXC_BAD_ACCESS) | Raw memory addresses unless symbolicated with .symbols.zip / .dSYM | Firebase 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 timeout | Yes / 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) Termination | OS kernel memory watchdog (Android lmkd or iOS Jetsam) killing the process when physical RAM is exhausted | Yes (Instant SIGKILL) — in-process handlers often cannot run before death | Foreground/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)
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:
Step 1: Generating .symbols.zip in Unity 6 (Android)
- Open File > Build Profiles (or Project Settings > Player > Android > Publishing Settings).
- Locate Debug Symbols (or
Create symbols.zipin earlier Unity versions):- Select
Publicfor standard release builds (produces a compact symbol package containing function names), orFullwhen you need exact C++ line numbers and DWARF debug tables.
- Select
- Build your Android App Bundle (
.aab). Unity outputs bothGame.aabandGame-1.0.0-v12.symbols.zipin your build folder (and embeds configurable symbols inside the.aabdepending 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.zipduring your CI/CD build step so Crashlytics symbolicates bothlibunity.soandlibil2cpp.so:BASH - iOS (
.dSYM): In Xcode (Organizer > Archives orBuild Settings > Debug Information Format = DWARF with dSYM File), upload the generated.dSYMbundle to Crashlytics via theupload-symbolsscript 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:
[!IMPORTANT] BuildId Matching Rule: Every IL2CPP compilation produces a unique GNU
BuildIdhash. You cannot symbolicate a crash from buildv12using the.symbols.zipgenerated by a later rebuild (v13), even if no C# code changed. Archive the.symbols.zipand.dSYMartifact 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:
Why this happens:
- On Android, Java UI events and Activity lifecycle callbacks (
onPause) run on themain(TID 1) thread, whereas the Unity engine loop (Update,LateUpdate, rendering, C# scripts) runs on a separate thread namedUnityMain. - When the player locks their screen, switches apps, or opens a full-screen rewarded video ad, the Android
mainthread callsUnityPlayer.pause()and waits on aSemaphoreforUnityMainto finish its current frame. - If
UnityMainis frozen—for example, executing synchronousFile.WriteAllText()insideOnApplicationPause(true), compiling a complex shader variant, synchronously deserializing a large asset, or waiting on a lock held by an ad SDK callback—themainthread's semaphore wait times out and Android triggers an ANR.
Actionable Fixes for Unity Android ANRs
- Always Scroll Down to the
UnityMainThread in the ANR Dump: Never stop reading atmain(tid=1). Search the ANR trace for"UnityMain"to see the exact C# or native function stalling the engine loop. - Keep
OnApplicationPause(bool pauseStatus)Lightweight: Players frequently background mobile games. Do not serialize megabytes of JSON or make blocking HTTP calls synchronously insideOnApplicationPause(true). Maintain an incremental dirty-state buffer and write small payloads asynchronously. - Replace Synchronous Asset Loads with Async Addressables: Loading large prefabs or scenes synchronously stalls
UnityMain. Stream assets asynchronously via Unity Addressables (LoadAssetAsync). - 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:
- Unity
CrashReportHandlerMetadata (UnityEngine.CrashReportHandler): If you use Unity Cloud Diagnostics (Backtrace integration), attach runtime metadata viaCrashReportHandler.SetUserMetadata("level_id", currentLevel)so Unity Editor-integrated reports carry custom state. - GameAnalytics Error Events (
GameAnalytics.NewErrorEvent): Connecting Unity'sApplication.logMessageReceivedcallback (with deduplication/rate-limiting so aNullReferenceExceptioninsideUpdate()does not flood HTTP queues) toGameAnalytics.NewErrorEventallows product managers to correlate error rates directly against D1/D7 retention and level progression drop-off funnels.
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.
Pre-Launch Crash Verification Checklist
[ ]Generate Symbols Enabled:Debug Symbolsset toPublicorFullfor Android IL2CPP builds andDWARF with dSYM Filefor iOS builds.[ ]Symbol Archive Stored:.symbols.zipand.dSYMartifacts archived in CI/CD and uploaded to Google Play Console and Firebase Crashlytics.[ ]StagingForceCrashVerified: TriggeredUtils.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.somemory offsets.[ ]OnApplicationPauseAudited: Confirmed zero blocking file I/O or synchronous asset loads occur during app backgrounding to preventUnityPlayer.pauseAndroid ANRs.
Frequently Asked Questions
Official Documentation & Related Unity Engineering Guides
Official Documentation References
- Unity 6 Manual: Android Debug Symbols (
libil2cpp.sym.so) - Unity 6 ScriptReference:
UnityEngine.Diagnostics.Utils.ForceCrash - Firebase Crashlytics Unity SDK Documentation
- Unity Cloud Diagnostics Documentation
Related Guides, Case Studies & Services on This Site
- GameAnalytics Unity SDK Setup (2026): Events, Progression & Error Tracking
- Unity Mobile Memory Profiling & OOM Crash Guide
- Unity 6 Mobile Game Optimization Guide
- Unity Mobile Performance Checklist for Android & iOS
- Unity Addressables Optimization: Memory & Loading Guide
- Case Study: Building & Shipping Bird Sort Mania in Unity in 20 Days
- Unity Game Development Services | Mobile Game Development Services — Need help diagnosing Android ANRs, fixing IL2CPP native crashes, or rescuing an unstable Unity build? Get in touch.
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
Updating Unity Mobile Games Without Store Submissions: Architecture & AssetBundle Fundamentals (Part 1)
Part 1 of the 3-part LiveOps masterclass. Learn how to dynamically update Unity mobile game content, levels, and assets over-the-air without submitting new binary builds to Apple & Google Play.
Mobile Game Multiplayer Architecture: Photon Fusion vs Mirror vs Dedicated Servers (2026)
An engineering guide comparing Photon Fusion, Mirror networking, and Dedicated Linux Servers for Unity mobile games. Includes CCU pricing, tick rates, and latency optimization.
GameAnalytics Unity SDK Integration Guide: Tracking D1/D7 Retention, Level Progression & ARPU
Learn how to install, configure, and instrument the GameAnalytics Unity SDK in C# to track FTUE onboarding funnels, level progression, virtual economies, IAP receipts, and D1/D7 retention.