Why Your Symbols Don't Match Your Binaries

Joey Plunkett — Wed, 15 Jul 2026 06:00:00 +0000

You uploaded the symbols. They're right there. And your crash report still comes back as a wall of hex addresses with no function names, or your debugger greys out the breakpoint and tells you symbols aren't loaded for a PDB that is very obviously sitting in the folder you're pointing at.

This is the single most maddening failure in native debugging, because everything looks correct. The file exists. The name matches. And it still doesn't work.

Here's what's actually going on, and why "the file is right there" was never the question.

Matching is by identity, not by name

When your compiler builds a binary, it stamps a unique identifier into it and writes the same identifier into the symbol file it generates. On Windows that's a GUID plus an Age (a signature and a revision counter). On macOS and iOS it's a UUID in the dSYM. The debugger doesn't look for a file called MyApp.pdb. It looks for the symbol file whose identifier matches the one baked into that exact binary.

If the identifiers don't match, the symbol file is treated as missing, not as close enough. That's deliberate. Symbols that almost match are worse than no symbols, because they'd map addresses to the wrong functions and send you chasing a bug in code that never ran. So the tooling refuses.

This is the whole thing. A symbol file isn't a description of your source code. It's a fingerprint of one specific compilation. Compile again and you get a different fingerprint, even if you changed nothing.

The causes, in order of how often they get people

You rebuilt. The most common one by far, and the most infuriating because your source didn't change. Hit rebuild and the compiler generates a fresh binary with a fresh Age, and the PDB you carefully saved from the previous build is now, formally, a different fingerprint. It's the same code, and it's not the same build. The debugger doesn't care about your feelings on this.

Debug and Release got crossed. Your toolbar says Debug, the module actually loaded came from a Release output path, and the symbols you're pointing at belong to the other one. Extremely common, weirdly hard to see, and the reason the Modules window exists.

Your release build never generated symbols in the first place. A release configuration set to strip debug info produces a binary with nothing to match against. There's no mismatch here, there's an absence. Check that your release config still emits PDBs. They don't ship to users, they go to your crash reporter.

The PDB was stripped. This one is genuinely sneaky. A PDB built with /PDBSTRIPPED loads successfully and contains no source mapping at all. The tooling reports symbols as loaded, you still get nothing useful, and you go hunting for a completely different bug. Symbols present, symbols useless.

Something modified the binary after it was built. This one catches game and desktop teams constantly. Code signing changes the executable's timestamp after the compiler is done with it. Anti-cheat and copy-protection wrappers rewrite the binary too. Either way, the thing your users are running is no longer byte-identical to the thing your symbols were generated against. The fix is to keep the signed executable, the one you actually shipped, not the pre-signing build output.

Something copied the binary somewhere else. Build systems, installers, and runtimes that shuffle binaries into temp directories can quietly separate a binary from its symbols, or leave a stale copy of one next to a fresh copy of the other.

You're chasing symbols that don't exist. Third-party libraries often don't publish matching PDBs at all. Microsoft's public symbol server covers system and framework DLLs, not somebody's proprietary DLL. Sometimes the fix is "there is no fix, this frame stays opaque."

There is a specific stage of symbol debugging where you find yourself staring at a PDB file, in the correct folder, with the correct name, and quietly asking it what more it wants from you. It wants a different Age. It will not tell you this.

How to actually check, instead of guessing

The good news about identity-based matching is that it's checkable. You don't have to theorize about whether your symbols match. Read the identifier out of both sides and compare.

Platform tooling handles this. On Windows, dumpbin and symchk will report the GUID and Age. On macOS, dwarfdump gives you the UUID. For Crashpad symbols, the GUID sits on the first line of each .sym file. There's also ChkMatch, an old but excellent tool that tells you directly whether a PDB matches a binary and why it doesn't when it fails ("Age mismatch" is a phrase you'll come to know).

I work at BugSplat, where we deal with this problem at volume, so we ended up open-sourcing a few small tools for reading these identifiers out of symbol files:

pdb-guid for Windows PDBs
macho-uuid for macOS and iOS dSYMs
elfy for ELF files

They do one thing, they're MIT licensed, and they'll tell you in about a second whether the symbol file in your hand belongs to the binary you're debugging. Use them, fork them, ignore them, whatever's useful.

The part that actually stings in production

All of the above is annoying on your own machine, where you can just rebuild and try again.

In production it's a different category of problem, and it's permanent. The crashes coming in from users were produced by a binary you shipped weeks ago. The only symbol file that will ever match it is the one generated at the moment that binary was built. If you didn't keep it, those crashes are unreadable, forever. There is no recovering it later, no rebuilding from the same commit, because a rebuild produces a new fingerprint.

The tag in git is not enough. The symbols are the artifact.

This is the whole reason symbol management is a discipline and not a chore. Every build that could reach a user, including QA and beta builds, has to have its symbols captured at build time, or you're accepting in advance that some future crash will be undebuggable.

How to stop fighting this

The fix is boring, which is how you know it's the right one: take the human out of it.

Upload or archive symbols automatically, from the build pipeline, on every build. Not as a step someone remembers, as a step that runs. If the symbols leave the build machine at the same moment the binary does, they cannot get out of sync, because there was never a window in which they could.

Concretely, that means:

Confirm your release config emits symbols. On Windows, set the debug information format so release builds produce PDBs.
Capture symbols as a build artifact, not as something on someone's machine.
Archive the post-signing binary too, since signing changed its timestamp.
Make the upload a pipeline step, so a build physically cannot ship without its symbols going somewhere durable.

Whether that "somewhere durable" is a symbol server you run, an artifact store, or a crash reporting service doesn't much matter. What matters is that it happens on every build, without a human deciding to do it.

For what it's worth, at BugSplat we solve step 4 with a CLI called symbol-upload that you drop into CI (there's a GitHub Action too). It walks your build output, reads the identifiers, and ships the symbols up so that when a crash lands six months later we can match it back by GUID rather than by filename and hope. But the principle is tool-agnostic, and if you're rolling your own symbol server with symstore, the same discipline applies.

The short version

Symbols match binaries by a unique identifier baked in at compile time, not by filename. Rebuild and the identifier changes, even if your code didn't. Sign or wrap the binary afterward and it changes too. So a symbol file is a snapshot of one specific build, and if you lose it, the crashes from that build are unreadable permanently.

When something looks wrong, read the GUID out of both sides and compare instead of guessing. And automate symbol capture from your build pipeline, so the window in which symbols can drift from binaries never opens.

If you've got a symbol horror story, I'd genuinely like to hear it. I collect them.