Fix: Unreal Packaged Build Crash on Startup

Here is how to fix Unreal packaged build crash on startup. Your game runs perfectly in the Unreal editor. You hit Package Project, the cook completes, and you launch the executable — instant crash. No window appears, or maybe the splash screen flashes for a frame before the process dies. This is one of the most common and demoralizing Unreal packaging issues, but the root cause almost always falls into one of four categories.

The Symptom

After packaging your project through File > Package Project (or via UAT on the command line), the resulting executable crashes immediately on launch. In some cases, the Windows crash dialog appears. In others, the process simply exits with no visible feedback at all. The editor continues to work perfectly with the same project, making the issue seem impossible to diagnose.

If you check the log file in the packaged build's Saved/Logs/ directory, you may find a fatal error referencing a specific asset path, a null pointer dereference during module startup, or a shader compilation failure. Sometimes the log is truncated because the crash happens before the logging system is fully initialized.

What Causes This

1. Missing cooked assets. The editor resolves assets directly from disk, including assets in directories that the cooker does not scan. If you load an asset through a string path at runtime — such as StaticLoadObject or LoadObject with a hard-coded reference — the cooker may not know about it. The asset is never included in the packaged build, and the load call returns null. If your code does not check for null, the next access crashes.

2. Hard-coded editor paths. Paths like /Game/StarterContent/Materials/M_Basic work in the editor because the content browser resolves them to files on disk. But if those assets are in a plugin or a directory excluded from cooking, they will not exist in the packaged build. This also applies to ConstructorHelpers::FObjectFinder used outside of a constructor context.

3. Unresolved soft references. TSoftObjectPtr and FSoftObjectPath references do not create hard dependency chains for the cooker. If the only reference to an asset is a soft reference stored in a data table or Blueprint variable, the cooker may skip it entirely. The asset loads as null at runtime, and the packaged build crashes where the editor did not.

4. Shader compilation errors. Some shader permutations compile in the editor but fail during cooking because the target platform shader compiler has stricter requirements. This is especially common when packaging for consoles or mobile, where shader model limitations are more restrictive than the development PC's GPU.

The Fix

Step 1: Find the crash point from the log. The first step is always to read the packaged build's log file. Add explicit logging around your asset loads so you can see exactly which one fails.

// Safe asset loading with logging for packaged builds
void AMyGameMode::LoadCriticalAssets()
{
    FSoftObjectPath AssetPath(TEXT("/Game/Data/DT_WeaponStats.DT_WeaponStats"));
    UObject* LoadedAsset = AssetPath.TryLoad();

    if (!LoadedAsset)
    {
        UE_LOG(LogTemp, Fatal, TEXT("Failed to load asset: %s"), *AssetPath.ToString());
        return;
    }

    UDataTable* WeaponTable = Cast<UDataTable>(LoadedAsset);
    if (!WeaponTable)
    {
        UE_LOG(LogTemp, Error, TEXT("Asset loaded but is not a DataTable: %s"), *AssetPath.ToString());
        return;
    }

    UE_LOG(LogTemp, Log, TEXT("Successfully loaded weapon data table with %d rows"), WeaponTable->GetRowMap().Num());
}

Step 2: Replace hard-coded paths with UPROPERTY references. Instead of loading assets by path string, expose them as properties that the editor and cooker can track.

// BAD: Hard-coded path that the cooker cannot track
// UMaterial* Mat = LoadObject<UMaterial>(nullptr, TEXT("/Game/Materials/M_Special"));

// GOOD: UPROPERTY reference that creates a cook dependency
UCLASS()
class AMyActor : public AActor
{
    GENERATED_BODY()
public:
    UPROPERTY(EditDefaultsOnly, Category = "Assets")
    TSoftObjectPtr<UMaterialInterface> SpecialMaterial;

    void ApplyMaterial()
    {
        UMaterialInterface* Mat = SpecialMaterial.LoadSynchronous();
        if (Mat)
        {
            MeshComp->SetMaterial(0, Mat);
        }
    }
};

Step 3: Add soft-referenced directories to the cook list. Open Project Settings > Packaging > Additional Directories to Cook and add every directory that contains assets referenced only through soft paths or string references. For data-driven content, also add Primary Asset Types in the Asset Manager settings.

// You can also force-cook assets from C++ using the Asset Manager
void UMyGameInstance::Init()
{
    Super::Init();

    UAssetManager& AssetManager = UAssetManager::Get();

    // Register a primary asset type to ensure all assets in a directory are cooked
    AssetManager.ScanPathForPrimaryAssets(
        FPrimaryAssetType(TEXT("WeaponData")),
        TEXT("/Game/Data/Weapons"),
        UDataAsset::StaticClass(),
        true  // bForceSynchronousScan
    );
}

Related Issues

If your packaged build launches but the AI does not navigate properly, see our guide on AI MoveTo not working. If materials appear correct in the editor but fail to update at runtime, check out material instances not updating at runtime.

Always check the log. The answer is in the log.