Cook Doctor for Unreal Engine 5.8

One damaged file. 1,779 error messages. One of them is true.

Truncate a single .uasset in an Unreal 5.8 project and cook it. Measured on a real run, with a clean control first. Every screenshot on this page shows this one cook, including the one taken inside Unreal Editor:

• 1,779 Package is unloadable accusations.
• 1 of them names the file that is actually broken.
• 1,775 of the false ones accuse your engine installation of being corrupt. Its bytes are perfect.
• And the cook quietly finished 418 packages where the clean control run finished 578, without saying so anywhere.

The size of the cascade is not a constant: four runs of this break produced 1,339, 1,412, 1,538 and 1,779 accusations, and the last two are the same file broken the same way. The shape never changed - one true cause, a false cascade in the thousands, most of it pointed at engine files that are byte-perfect.

The natural reading of that log is "my engine install is broken, verify or reinstall it". That is an afternoon spent on the wrong thing, and it is what the log invites you to do.

Why Unreal says it

PackageReader.cpp:159 prints "Reason: Invalid value for PACKAGE_FILE_TAG at start of file" from a branch that fires on a bad tag or on the reader already being in an error state. The message names one cause for a two-cause condition. So most of those lines are a claim about the first four bytes of a file that the engine never checked.

What Cook Doctor does

It reads the four bytes.

For every accusation in your cook log it opens the accused file, reads its first four bytes, and compares them with PACKAGE_FILE_TAG. Four bytes per file, not a load, so a cascade this size is answered in about a second.

• Names the damaged package with its evidence - header intact, body truncated: the reader wanted 9,642 bytes with 4,113 remaining, and the file is 12,504 bytes.
• Disproves every other accusation individually and tells you how many of them were pointed at your engine install, so you do not spend the afternoon reinstalling it.
• Refuses to answer when the log and the project no longer correspond. If an accused file changed after the cook, its bytes are not evidence about that cook. It names the drifted files and stops, instead of giving you a confident wrong answer.
• Repairs, reversibly. -Fix moves the damaged file into a timestamped quarantine, writes a journal, and lists the packages that referenced it. -Undo puts it back. Nothing is deleted, and nothing outside your project is ever touched.
• Prefers your version control over its own repair. If it finds a .git, .svn or p4config at or above the project, the report leads with git checkout -- <file>, because restoring the real bytes beats quarantining the asset.
• Proves the repair instead of asserting it. -Prove compares the failing log with the re-cook and prints the two numbers that matter. On the fixture run above: accusations 1779 -> 0 and packages 418 -> 578. Your numbers will differ - the size of the false cascade is not a constant. What reproduced across runs is the shape: one true cause, a large false cascade after it, both gone once the damaged package is dealt with.

For CI

Runs as a commandlet with a documented exit code table. 4 means a damaged package was named - that is the one to gate a build on. 3 means every accusation was disproved and the tool cannot answer, which is deliberately not the same as clean. A designed HTML report for a human, and a complete JSON report for a machine, chosen by the file extension.

Honest scope

One failure class is measured: a truncated or partially written package, which is what an interrupted save, a partial sync or a bad LFS checkout produces. Cook failures have other causes, and this tool will tell you it found nothing rather than invent a culprit. Built and run against UE 5.8 only, because that is the only version it has been verified on.

What you get

Full C++ source, no obfuscation, no binaries-only module. Editor console command and commandlet. Zero third-party dependencies beyond the engine.

AI disclosure: Code - yes. Graphics - yes. Sounds - no. Text and Dialog - no.

Full documentation, including the switch reference and the exit-code table: Cook Doctor README.

More from CSAF

More Unreal Engine plugins from the same studio:

• Asset Sentinel - Repairs the Unreal Engine 5 Assets That Break Your Standards
• Migration Ledger - find AND FIX what an Unreal upgrade silently broke
• Blueprint Straightedge - Project-Wide Blueprint Graph Layout for UE5
• Source Link

Everything else we make is at csaf.itch.io.