stride3d/stride · error · InvalidOperationException

Invalid bundle header

Error message

Invalid bundle header

What it means

ReadBundleDescription validates the bundle's magic header after deserializing it; a mismatch with Header.MagicHeaderValid throws InvalidOperationException. The stream being read is not a valid Stride bundle file (wrong format, corrupted, or truncated at the start).

Solutions

1. Point the loader at a genuine .bundle file produced by Stride's packager, not an arbitrary file.
2. Re-transfer/re-generate the bundle; verify with checksum comparison against the build output.
3. Confirm the runtime Stride version can read bundles written by the build tool version.

Example fix

// before
var bundle = ReadBundleHeader("logo.png"); // wrong file type
// after
var bundle = ReadBundleHeader("bundles/logo.bundle");

static readonly byte[] MagicHeaderValid = { /* Stride bundle magic */ };
static bool LooksLikeBundle(string path)
{
    using var fs = File.OpenRead(path);
    Span<byte> head = stackalloc byte[MagicHeaderValid.Length];
    return fs.Read(head) == MagicHeaderValid.Length && head.SequenceEqual(MagicHeaderValid);
}

try
{
    var bundle = ReadBundleHeader(bundleUrl, out var files);
}
catch (InvalidOperationException ex) when (ex.Message == "Invalid bundle header")
{
    throw new InvalidDataException($"{bundleUrl} is not a valid Stride bundle (bad magic header).", ex);
}

When it happens

Trigger: ReadBundleHeader/CreateBundle reading a file that is not a bundle (e.g. a plain asset or text file renamed to .bundle), a corrupted download, or a byte-order/version mismatch from a different Stride serialization version.

Common situations: Manually renamed data files, partial uploads/ftp transfers in ASCII mode, mixing bundle files between incompatible engine versions.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• Bundle has not been properly written
• Bundle could not be resolved
• Bundle is being loaded twice (either cyclic dependency or…
• Bundle has not been loaded.
• Can't pack files.

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

Appendix: source

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

    /// or
    /// Bundle has not been properly written
    /// </exception>
    public static BundleDescription ReadBundleDescription(Stream stream)
    {
        var binaryReader = new BinarySerializationReader(stream);

        // 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;

View on GitHub (pinned to 96fad776d2)