stride3d/stride · error · InvalidOperationException

Bundle has not been properly written

Error message

Bundle has not been properly written

What it means

After the magic header check, ReadBundleDescription compares the header's recorded Size with the actual stream length; if they differ it throws InvalidOperationException 'Bundle has not been properly written'. The bundle file is truncated (partially written) or extra data was appended.

Solutions

  1. Regenerate the bundle with CreateBundle / the asset build pipeline to produce a complete file.
  2. Delete partial bundles before re-running the build so stale truncated files are not reused.
  3. Add a post-build size/hash check that compares header.Size or file hash before shipping.

Example fix

// before
copyFile(tmpPath, finalPath); // copy may race with writer
// after
waitForWriteComplete(tmpPath);
verifyBundleSize(finalPath, expectedHeaderSize);
copyFile(tmpPath, finalPath);
Defensive patterns

Strategy: validation

Validate before calling

var fileInfo = new FileInfo(bundleUrl);
using var stream = File.OpenRead(bundleUrl);
// header.Size is at a fixed offset in the bundle header; compare against stream length before full read
if (ReadHeaderSize(stream) != stream.Length)
    throw new InvalidDataException($"{bundleUrl} is truncated or has trailing data.");

Try / catch

try
{
    var bundle = ReadBundleHeader(bundleUrl, out var files);
}
catch (InvalidOperationException ex) when (ex.Message == "Bundle has not been properly written")
{
    DeleteCorruptBundle(bundleUrl);
    RegenerateBundle(bundleUrl); // rebuild from source assets
}

Prevention

When it happens

Trigger: Reading a bundle file whose header.Size != stream.Length — interrupted CreateBundle write, disk-full during packaging, crash mid-write, or a truncated download.

Common situations: Build machine killed during packaging; copying files while they were still being written; network transfer cut off; incremental bundle update failing midway.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/f6d9fca64e415648. Report an issue: GitHub.

Appendix: source

Thrown at sources/core/Stride.Core.Serialization/Storage/BundleOdbBackend.cs:398

        // Read header
        var header = binaryReader.Read<Header>();

        var result = new BundleDescription
        {
            Header = header
        };

        // Check magic header
        if (header.MagicHeader != Header.MagicHeaderValid)
        {
            throw new InvalidOperationException("Invalid bundle header");
        }

        // Ensure size has properly been set
        if (header.Size != stream.Length)
        {
            throw new InvalidOperationException("Bundle has not been properly written");
        }

        // Read dependencies
        var dependencies = result.Dependencies;
        binaryReader.Serialize(ref dependencies, ArchiveMode.Deserialize);

        // Read incremental bundles
        var incrementalBundles = result.IncrementalBundles;
        binaryReader.Serialize(ref incrementalBundles, ArchiveMode.Deserialize);

        // Read objects
        var objects = result.Objects;
        binaryReader.Serialize(ref objects, ArchiveMode.Deserialize);

        // Read assets
        var assets = result.Assets;
        binaryReader.Serialize(ref assets, ArchiveMode.Deserialize);

View on GitHub (pinned to 96fad776d2)