Convert Mono PDB Symbols to MDB with pdb2mdb

A .NET build on Linux under Mono gives you a Microsoft-format PDB, and the Mono debugger wants the older MDB format instead; pdb2mdb bridges that gap. It converts the PDB tied to a .dll or .exe, and this guide checks the result lands correctly beside the assembly. Examples use pdb2mdb from Ubuntu's mono-devel package, version 6.8.0.105+dfsg-3.6ubuntu2.

Allow about ten minutes. You need a shell, a readable managed assembly with its matching .pdb, and write permission in that directory. This changes the symbol files next to the assembly but never the assembly itself. Don't run it against a production directory until you have a backup or a rebuild path ready.

1. Confirm the installed tool

Check which executable will run and note the package version. Both are ordinary read-only commands, no elevated privileges required:

$ command -v pdb2mdb
/usr/bin/pdb2mdb
$ dpkg-query -W -f='${Package} ${Version}\n' mono-devel
mono-devel 6.8.0.105+dfsg-3.6ubuntu2
$ pdb2mdb --help
Mono pdb to mdb debug symbol store converter
Usage: pdb2mdb assembly

The installed command describes its argument as an assembly, not a standalone PDB path. Give it the .dll or .exe. The converter finds the associated PDB itself and writes Mono debugging information next to it.

2. Inspect the assembly and symbol pair

Move to a working copy or build-output directory, then list the files without touching them:

$ cd /path/to/build-output
$ ls -l MyLibrary.dll MyLibrary.pdb
-rw-r--r-- 1 alice alice  9216 Sep 25 10:20 MyLibrary.dll
-rw-r--r-- 1 alice alice  4096 Sep 25 10:20 MyLibrary.pdb

Swap in real values for /path/to/build-output and MyLibrary. The names have to match the assembly and its PDB exactly. A PDB from a different build can still look plausible while producing misleading line numbers, so keep the pair from one single compiler output.

A file ending in .pdb isn't automatically enough. The manpage describes PDB files as being associated with a library or executable, and the installed program expects the assembly itself as input. If either file is missing or unreadable, fix the build output or the permissions first; don't reach for sudo as a first response.

3. Preserve the existing MDB file

Before converting, check whether an MDB file already exists:

$ ls -l MyLibrary.dll.mdb
ls: cannot access 'MyLibrary.dll.mdb': No such file or directory

No output file is the simplest case. If one exists, don't overwrite it blindly: the command is a converter, not a versioned backup system. Make a recoverable copy in the same directory, keeping its metadata intact:

$ cp --preserve=all -- MyLibrary.dll.mdb MyLibrary.dll.mdb.before-pdb2mdb
$ ls -l MyLibrary.dll.mdb MyLibrary.dll.mdb.before-pdb2mdb

That copy changes the directory, so check the destination and confirm you have enough free space first. If the conversion produces something unwanted, restore the backup only after stopping any process that might be reading the symbols:

$ mv -- MyLibrary.dll.mdb.before-pdb2mdb MyLibrary.dll.mdb

4. Convert the assembly's PDB

Run the converter against the assembly path. This is an ordinary user command as long as the build directory is writable:

$ pdb2mdb ./MyLibrary.dll
$ printf 'exit status: %s\n' "$?"
exit status: 0

A successful run normally produces no progress output at all. The result that matters is the new MDB file appearing beside the assembly:

$ ls -l MyLibrary.dll MyLibrary.pdb MyLibrary.dll.mdb
-rw-r--r-- 1 alice alice  9216 Sep 25 10:20 MyLibrary.dll
-rw-r--r-- 1 alice alice  4096 Sep 25 10:20 MyLibrary.pdb
-rw-r--r-- 1 alice alice  3584 Sep 25 10:21 MyLibrary.dll.mdb

Sizes and timestamps will differ on your machine. Check the exit status right away, before another command overwrites $?. A zero status says the converter finished; it doesn't prove the PDB actually matched the assembly, or that every debugger will pick up the symbols.

5. Check the output and the runtime layout

Confirm the output is a regular, non-empty file sitting beside the assembly rather than in some separate symbols directory:

$ test -s MyLibrary.dll.mdb && echo 'MDB file is non-empty'
MDB file is non-empty
$ file MyLibrary.dll.mdb
MyLibrary.dll.mdb: data

The manpage's key layout rule is the one that matters here: Mono debugging information lives side-by-side with the program executable or library. Keep MyLibrary.dll and MyLibrary.dll.mdb together whenever you copy the application to a test machine, and never rename just one of them.

Now exercise the assembly under the Mono runtime or debugger that actually needs the symbols. A stack trace with real source line numbers tells you far more than a file size ever will. Use the application's normal test command, not a production service, and keep the original PDB around until the result checks out.

6. Diagnose a failed conversion

For a missing or invalid input, the installed wrapper prints its usage and returns non-zero:

$ pdb2mdb /tmp/does-not-exist.dll
Mono pdb to mdb debug symbol store converter
Usage: pdb2mdb assembly
$ printf 'exit status: %s\n' "$?"
exit status: 1

Check the exact assembly path, then check read and write access without touching ownership or permissions:

$ test -r ./MyLibrary.dll && echo 'assembly is readable'
$ test -r ./MyLibrary.pdb && echo 'PDB is readable'
$ test -w . && echo 'directory is writable'

If the directory isn't writable, use a writable build copy or have its owner run the conversion. Don't run the command as root just to hide a permissions problem: elevated privileges can leave root-owned output behind and break your next build.

If the command succeeds but the debugger shows no line information, first confirm the MDB sits beside the exact assembly being executed. Then rebuild the assembly and PDB together and convert again. Don't copy a symbol file from another build just because the filenames match.