About Debugging Symbols

Understand how debugging symbols map program addresses to function names for readable crash stack traces.

Read time 2 minutes

Last updated a day ago

Important

Cloud Diagnostics is deprecated, and will be phased out in future versions of Unity. For more robust reports and device information, including information on Application Not Responding (ANR) errors for Android, use the diagnostics experience available in Unity 6.2 and later. For information about migrating from Cloud Diagnostics, refer to Migrate to Diagnostics in the Unity Dashboard.

Symbols map program addresses to function names. They allow crash and exception reports to provide a native crash stack trace with human-readable function names, instead of numerical addresses. They can be contained within the executable itself, but are usually stored in a separate file to reduce executable size. Crash and Exception Reporting works with two sets of symbols:

System (OS) symbols: System symbols are generated by the operating system supplier and come in different formats depending on OS. Apple platforms use dSYM folders, Android symbols are stored in .so files, and Windows symbols are stored in .pdb files. Unity supports symbols generated by Apple, Google, and Microsoft.
Application (Unity) symbols: Application symbols are auto-generated when you build your Unity project.

If your crash and exception reports contain missing symbol files, it can be harder to diagnose issues since they appear as numerical addresses. With the Crash and Exception Reporting service, you may upload symbol files to help identify issues in reports.

Understanding missing system symbols

Symbol files have a universally unique identifier (UUID) or globally unique identifier (GUID) that must exactly match the ID of the executable. Crash and Exception Reporting generates the following errors if the service cannot load a symbol file with an ID that matches a library or module:

<system symbols missing>
<symbols missing for uuid: xxx...>

If this happens, the issue typically is that Cloud Diagnostics does not have the symbols for that version of the operating system. For iOS and other Apple platforms, it can be difficult to obtain the symbols for older versions of an operating system. If you encounter this situation, you may check to see if you have similar crash reports for another version of the operating system. If you do, you might be able to resolve the issue by debugging in that version of the operating system.

Understanding missing application symbols

Reports where the application symbols are missing contain a line in the stack trace: <symbols missing for uuid: xxx...> When building a project on which Crash and Exception Reporting is enabled, Unity generates a symbol file and uploads it to the Crash and Exception Reporting servers. If this process fails, a symbols missing message appears in the Unity Dashboard. To troubleshoot failures in the symbol upload, check the symbol_upload.log file located in the same folder as the main Unity log. It should indicate which symbols were found and processed, along with any errors that occurred while processing and uploading those symbols.

What’s next?

If your Crash and Exception reports contain missing symbols, upload symbol files from the Dashboard. See Uploading symbol files.

Documentation

Development

User Acquisition

Monetization

Industry