Exceptions & hard crashes

01Crash or message? Read the last line

DepotDownloader fails in two completely different ways, and they need opposite responses:

Almost everything below sorts into those two bins. The mistake I made early on was reading the top of the dump and panicking; the bottom line is where the answer is. If your last line is a tidy sentence, jump to section 02 and the page it points you at. If it's a stack trace, the named-exception sections (03–06) tell you which ones are known, which are your environment, and which are genuinely worth a GitHub issue.

02The "Error:" lines are usually you (and that's good news)

These are handled errors — the tool printed them on purpose and exited cleanly. They look alarming and aren't. Here are the common ones and where each is actually solved:

The pattern: a clean sentence is the tool doing its job. Fix the input and rerun. Everything from here down is the other category — actual exceptions.

03NullReferenceException

System.NullReferenceException: Object reference not set to an instance of an object. — the most generic .NET crash there is. In DepotDownloader's history it had two specific triggers, both now largely guarded against in current builds:

• No Steam session. If login silently failed first — you'll see Timeout connecting to Steam3 or Unable to get steam3 credentials just above — older versions then tried to check your access with no session and dereferenced null. The fix is upstream: solve the login failure, and the NRE never happens.
• A depot whose parent app you don't own. Some depots belong to a different app (a shared runtime, a base game behind a DLC); anonymously or without that license, the manifest lookup came back null. Logging in with an account that owns the parent, or naming the right depot and app IDs, resolves it.

If you hit a fresh, reproducible NullReferenceException on a current version with a valid login, that's genuinely unexpected — it belongs in section 07's bug report, because the known causes are guarded now.

04OverflowException on huge depots

This one is real, still reachable, and specific to very large downloads:

The cause is arithmetic, not your setup: the tool sums file sizes across the depot, and on a big enough depot that running total overflowed a 32-bit integer (the original report, issue #7, was fixed, but the size-summing surface still exists for genuinely enormous depots). Two practical notes:

• Update first. If your binary is old, a newer release may already handle your case — always the cheapest first move.
• Then report it, because on current versions this is a true edge-case bug, not something you configured wrong. Include the app and depot IDs (the size is the whole point) so it can be reproduced.

Note the AggregateException: One or more errors occurred wrapper around it — that's .NET's envelope for a failure inside an async task. Whenever you see it, read past it to the ---> line: the inner exception after that arrow is the real story, here the overflow.

05IOException: files, locks & disk

File-system exceptions are the most common "real" ones, and they're almost always environmental — something about where you're writing, not the tool:

• The process cannot access the file because it is being used by another process. Something else holds a handle on the file being written — antivirus mid-scan, the game itself running, a search indexer, or a second DepotDownloader instance pointed at the same folder (issue #532). Close the culprit, exclude the folder from real-time AV, and don't download into a folder a running game has open.
• Lock violations on a NAS or network mount. Writing directly to an SMB/NFS share can throw file-locking IOExceptions that never happen on local disk (issue #26). Download to a local drive, then copy to the share — the same advice the pre-allocation freeze ends up at.
• There is not enough space on the disk. Because files are allocated at full size up front, a too-small disk crashes early, during pre-allocation (issue #220) — and a disk that fills mid-download can drop the process outright. Size for the uncompressed total; the stuck-or-corrupt page has the full disk story.

One honest caveat: PathTooLongException, Could not find a part of the path and similar path errors get attributed to DepotDownloader a lot, but I couldn't tie any of them to a confirmed report against the tool. If you hit one, treat it as ordinary Windows path behaviour first — shorten a deep -dir, avoid the 260-character limit, check the folder exists — before assuming it's a DepotDownloader bug.

06Crashes before it even starts

A different class: the process dies (or never appears) before any download logic runs. The two most common — the libicu/ICU error on minimal Linux, and "You must install or update .NET" on the framework build — have their own home on the it-won't-even-start page. Three others worth naming here because they look like crashes and aren't logic bugs:

• The CET / shadow-stack assert on unpatched Windows 10. A startup line like CLR: Assert failure … !AreShadowStacksEnabled() is a known interaction between recent .NET and a kernel bug on un-updated Windows 10 (issue #618, confirmed by a maintainer). The fix is to update Windows — you don't need Windows 11, just current patches.
• The library 'libhostpolicy.so' … was not found … Failed to run as a self-contained app. This means a self-contained build was launched through dotnet (or renamed to .dll). It doesn't need the runtime — run the binary directly (./DepotDownloader, not dotnet DepotDownloader.dll). See issue #457.
• It "opens and closes instantly." Not a crash at all — it's a command-line program with no window. Double-clicking it just prints the usage text and exits. Run it from an open terminal with arguments; the getting-started flow shows the shape.

07Reporting a real one

Once you've ruled out the handled errors and the environmental IO cases, what's left is worth the maintainers' time — and a good report gets fixed far faster. Include four things: your exact command (mask the password), the full output including the entire stack trace (not a cropped screenshot — the at … lines are the diagnosis), your OS and version, and the DepotDownloader version. File it on the issue tracker.

And one to expect but not panic over: a Stack overflow. that appears after "Total downloaded…" — during Steam disconnect — has been seen on Alpine Linux with the newest .NET (issue #642). It's a teardown-phase glitch: your files are already written and intact. Annoying, cosmetic, worth reporting — but it didn't cost you the download. As always, the cheapest first step before reporting anything is to update to the latest release and try once more; a surprising share of "crashes" are just an old binary meeting a changed Steam.