Why can't I just ship a debug build to get readable stack traces?

Debug builds are dramatically larger (often 3-5x the size of a release build), run slower due to disabled optimizations, and contain symbol information that can help reverse engineers understand your game's internals. For public releases, you should always ship a stripped release build. Symbolication lets you have it both ways: ship a lean release build to players, but retain the symbol files privately so you can decode crash addresses after the fact.

What happens if my symbol file is from a different build than the crash?

Mismatched symbolication produces garbage output. Address 0x1a2b3c4d in build v1.3.1 points to a completely different function than the same address in build v1.3.2. If you apply the wrong symbol file, the stack trace will show function names that have nothing to do with the actual crash. This is worse than no symbolication because it actively misleads you. Always store symbol files keyed by build version and build ID.

Do I need to keep symbol files forever?

Keep symbol files for as long as players are using that build. On Steam, significant numbers of players may be on a version from 6-12 months ago if they have auto-updates disabled or if you support branch switching. A practical rule: keep symbol files for the current version plus the previous 3-5 major releases. For mobile builds, Apple and Google keep crash data for 90 days, so symbol files need to cover that window.

Does Godot generate symbol files for GDScript?

GDScript runs on the Godot virtual machine, so GDScript-level crashes produce readable stack traces without symbolication — the VM knows function names natively. Symbolication is needed for crashes in Godot's native C++ engine code or in GDExtension/C# code. When you export a Godot project with debug symbols enabled, the export process generates a .pdb file (Windows) or separate debug binary (Linux) for the engine layer.

Game Crash Symbolication: Turning Raw Addresses into Readable Stack Traces

Quick answer: Symbolication converts raw memory addresses in crash reports into function names and line numbers using symbol files (.pdb on Windows, .dSYM on Mac/iOS) generated at build time. Upload these files to your crash reporter keyed by build version, and every crash report becomes a readable stack trace instead of a column of hex numbers.

A crash report without symbolication looks like a ransom note written in hexadecimal. 0x00007FF612A4B3C1, 0x00007FF612A3E890, 0x00007FF612C1024F — the addresses tell you a crash happened and vaguely where in memory execution was, but nothing about which function caused it or which line of code. Symbolication is the process that turns those addresses back into readable, actionable stack traces. Understanding it is non-negotiable for any studio that ships release builds.

What Symbolication Actually Does

When a compiler builds your game for release, it applies optimizations — inlining functions, reordering instructions, eliminating dead code — and then strips the debug information from the final binary. Stripping removes the mapping table that connects memory addresses to source file names, function names, and line numbers. The result is a smaller, faster binary that’s harder to reverse engineer. But it also means that when the binary crashes and the operating system records a stack trace, all you get are raw addresses.

Symbolication works by applying the mapping table — stored separately in a symbol file — to those raw addresses after the crash. The symbol file is generated during the build process at the same time as the binary, so the mapping is exact. Given address 0x00007FF612A4B3C1 and the matching symbol file, a symbolication tool can tell you: “this is line 247 of InventoryManager.cpp, inside the function InventoryManager::AddItem.”

The critical constraint: the symbol file must come from the exact same build as the binary that crashed. Recompiling the same source code produces different addresses because compiler output is not deterministic across builds.

Symbol File Formats by Engine and Platform

Each platform and engine has its own symbol file format. Knowing which format to generate saves a lot of confusion:

Windows (.pdb): Program Database files. Generated by MSVC and compatible compilers. Unity generates a .pdb alongside the Windows build when you enable “Create Visual Studio Solution” or use IL2CPP with debug symbols enabled. Godot’s Windows exports include a .pdb when exported with “Export With Debug” turned off but “Debug Symbols” retained (export template dependent).
macOS / iOS (.dSYM): Debug Symbol bundles. Xcode generates these automatically. Unity’s iOS build process produces a .dSYM bundle in the Xcode project output. macOS standalone builds generate one if you build through Xcode or use the dsymutil tool on the output binary.
Android (.so + mapping.txt): Android uses unstripped shared libraries (.so files) for native symbolication, plus mapping.txt for ProGuard-obfuscated Java/Kotlin code. Unity exports a Symbols.zip containing the unstripped libraries.
Linux (debug binary): Separate debug binary generated with objcopy --only-keep-debug, or DWARF debug info retained in a split debug file. Less standardized than other platforms.

Generating Symbol Files in Unity

Unity’s IL2CPP backend (required for iOS, optional for other platforms) generates native code that needs symbol files. To get symbol files from a Unity build:

// In your BuildPlayerOptions or via Build Settings UI:
BuildPlayerOptions options = new BuildPlayerOptions();
options.options = BuildOptions.None; // NOT BuildOptions.Development

// For IL2CPP Windows builds, set in Player Settings:
// Scripting Backend: IL2CPP
// Create Visual Studio Solution: enabled (generates .pdb)

// For Android, in Player Settings:
// Scripting Backend: IL2CPP
// Split Application Binary: enabled
// Under Build Settings > Build > check "Create symbols.zip"

Unity produces a Symbols.zip archive alongside the build. This archive contains the unstripped .so files for Android or .pdb files for Windows. Store this archive alongside the build artifact, keyed by version number.

Generating Symbol Files in Godot

Godot’s export templates come in two flavors: release and debug. The release template is stripped. To get symbols for a Godot release build, you need to either export with the debug template (not recommended for distribution) or build a custom export template with symbols separated:

# Build Godot with debug symbols separated (Linux example)
scons platform=linuxbsd target=template_release debug_symbols=yes separate_debug_symbols=yes

# This produces:
#   godot.linuxbsd.template_release.x86_64          (stripped, ship this)
#   godot.linuxbsd.template_release.x86_64.debug    (symbols, keep this)

# For Windows, the MSVC build produces a .pdb alongside the .exe
scons platform=windows target=template_release debug_symbols=yes

For most indie studios using Godot, the practical approach is to retain the full unstripped export binary privately as your symbol artifact, even though you ship the stripped version. Tools like addr2line on Linux or llvm-symbolizer can then process crash addresses against the debug binary.

The Symbolication Pipeline

The pipeline has three steps: crash capture, address storage, and symbolication on demand.

Crash capture: The crash reporter SDK catches the crash signal, collects the stack of return addresses from the call stack, and transmits them along with the game’s build version to the server.
Storage: The server stores the raw addresses indexed by build version. No symbolication happens at capture time — this keeps the SDK fast and ensures you don’t need the symbol file available at the moment of the crash.
Symbolication on demand: When you view a crash report (or when the server processes it in a background job), it looks up the symbol file for that build version, runs the symbolication tool, and replaces raw addresses with human-readable frames.

Bugnet handles steps 2 and 3 automatically once you upload a symbol file. Navigate to your project’s symbol files page, upload the archive for each build version, and all existing and future crash reports from that build are automatically symbolicated. The raw addresses are retained so you can re-symbolicate if you ever need to update the symbol file.

What Happens When Symbol Files Are Missing or Mismatched

If you don’t upload a symbol file, crash reports show raw addresses. This is annoying but at least honest — you know you’re looking at unsymbolicated data.

A mismatched symbol file is more dangerous. If you apply a symbol file from build v1.3.1 to a crash from v1.3.2, the output looks plausible but is wrong. The addresses map to different functions because the code was recompiled. You might spend an hour investigating a crash in InventoryManager::AddItem when the real crash is in a completely different subsystem.

The safeguard is build IDs. Modern symbol formats embed a build ID (a hash of the binary) into both the executable and the symbol file. A symbolication tool that respects build IDs will refuse to apply a mismatched symbol file and report an error instead of producing garbage output. Always verify that your crash reporter checks build IDs before symbolication.

“A mismatched symbolication is worse than no symbolication. At least a column of hex addresses tells you honestly that you don’t know what broke.”

Integrating Symbol Upload into Your Release Process

The easiest way to ensure symbol files are always available is to make their upload a required step in your release checklist — or better, automate it in your CI/CD pipeline so it can’t be forgotten.

# Example: upload symbols to Bugnet as part of a GitHub Actions release job
- name: Upload symbols
  run: |
    VERSION=$(cat version.txt)
    # Upload Android symbols
    curl -X POST https://api.bugnet.io/api/v1/projects/"$PROJECT_SLUG"/symbols \
      -H "Authorization: Bearer $BUGNET_TOKEN" \
      -F "version=$VERSION" \
      -F "platform=android" \
      -F "file=@build/Symbols.zip"
    # Upload Windows symbols
    curl -X POST https://api.bugnet.io/api/v1/projects/"$PROJECT_SLUG"/symbols \
      -H "Authorization: Bearer $BUGNET_TOKEN" \
      -F "version=$VERSION" \
      -F "platform=windows" \
      -F "file=@build/GameName_Data/Plugins/x86_64/GameAssembly.pdb"

Add this step immediately after the build step and before the deployment step. If symbol upload fails, fail the release. A deployed build without symbol files is a build you can’t effectively debug.

Store symbol files in durable, versioned storage. Your crash reporter may need them months later when a player finally updates from an old version. Don’t rely solely on the crash reporter’s symbol storage — keep an independent copy in your artifact storage (S3, B2, GCS) keyed by platform and version.

Symbolication for Scripting Languages

Native crash symbolication applies to compiled code. Scripting languages have their own story:

GDScript (Godot): The Godot VM reports script crashes with readable function names and line numbers natively. No symbolication needed for GDScript-only crashes.
C# (Unity, Godot): IL2CPP compiles C# to native code, so crashes in IL2CPP builds need native symbolication. Mono builds keep managed stack traces readable but lose native frames.
Lua, JavaScript, Python: VM-level crashes report script line numbers. Engine-level crashes below the VM still need native symbolication.

The common scenario in a Unity IL2CPP build is a crash report that mixes symbolicated native frames with managed C# frames from the IL2CPP type mapping. Bugnet merges both into a single readable trace, using the LineNumberMappings.json that Unity generates alongside the IL2CPP output to correlate native addresses back to original C# source lines.

Upload the symbol file before you push the build to Steam. Not after the first crash report comes in.