Introduction to debugging symbols

Use debugging symbols to view stack traces in a human-readable format.

Read time 1 minute

Last updated 2 months ago

Symbols map program addresses to function names. They allow issues 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. Issues work with the following symbols:

Operating system (OS) symbols: System symbols are generated by the OS 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 issues contain missing symbol files, it can be harder to diagnose the issues because they appear as numerical addresses. With Diagnostics, you can upload symbol files through either the Unity Dashboard or CI/CD pipelines to help identify issues in reports.

System symbols

Symbol files have a universally unique identifier (UUID) or globally unique identifier (GUID) that must exactly match the ID of the executable. Diagnostics 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 Diagnostics doesn't have the symbols for that OS version. For iOS and other Apple platforms, it can be difficult to obtain the symbols for older OS versions. If you encounter this situation, you can check if you have similar crash reports for another OS version. If you do, you might be able to resolve the issue by debugging in that OS version.

Application symbols

When building a project on which diagnostic data is enabled, Unity generates a symbol file and uploads it to the Diagnostics servers. If this process fails, a

symbols missing

message appears in the Unity Dashboard. Reports with missing application symbols contain a line in the stack trace: <symbols missing for uuid: xxx...> 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.

Documentation

Development

User Acquisition

Monetization

Industry