stride3d/stride · error · InvalidOperationException

Invalid Format from DDS HeaderDX10

Error message

Invalid Format from DDS HeaderDX10 

What it means

The DX10 header stores the texture format as a DXGI format. DecodeDDSHeader checks description.Format.IsValid after reading it; if the DXGIFormat enum value is not a known/valid format in this Stride build, parsing is aborted with this error, because no pixel format conversion mapping exists.

Solutions

1. Re-export the DDS with a widely supported DXGI format (e.g. BC1/BC3/BC7, R8G8B8A8)
2. Update Stride to a version that supports the newer DXGI format
3. Convert the texture to PNG/TGA then re-import through the engine pipeline
4. Verify the file with a DDS viewer to confirm the declared format

Example fix

// before (DDS DX10 header DXGIFormat)
DXGIFormat = 95 // unknown to this Stride version
// after
DXGIFormat = 71 // DXGIFORMAT_BC1_UNORM

// Read DXGIFormat from DX10 header (offset 128+20+4) and compare against supported set
var dxgiFormat = BitConverter.ToUInt32(ddsBytes, 128 + 24);
if (!Enum.IsDefined(typeof(PixelFormat), (int)dxgiFormat) /* or not in supported mapping */)
    throw new NotSupportedException($"DDS uses DXGI format {dxgiFormat} not supported by this engine build");

try { image = Image.Load(ddsBytes); } catch (InvalidOperationException ex) when (ex.Message.Contains("Invalid Format from DDS HeaderDX10")) { // re-export or convert texture
    throw new AssetLoadException("Unsupported DDS DXGI format; re-export with BC1/BC3/BC7 or R8G8B8A8", ex); }

When it happens

Trigger: Loading a DDS whose HeaderDXT10.DXGIFormat is an unknown/newer DXGI value (e.g. newer formats added in later DirectX SDKs) or an invalid value, on a Stride version whose PixelFormat mapping doesn't include it.

Common situations: DDS exported by very new tools using DXGI formats Stride doesn't know, hand-edited/corrupted headers, version drift between tooling and engine.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Pointer to DDS header cannot be null
• Unexpected ArraySize == 0 from DDS HeaderDX10
• Unexpected Height != 1 from DDS HeaderDX10
• Texture3D missing HeaderFlags.Volume from DDS HeaderDX10
• Unexpected ArraySize > 1 for Texture3D from DDS HeaderDX10

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

Appendix: source

Thrown at sources/engine/Stride.Foundation/Graphics/DDSHelper.cs:335

                description.MipLevels = 1;

            // Check for DX10 extension
            if ((header.PixelFormat.Flags & DDS.PixelFormatFlags.FourCC) != 0 && (new FourCC('D', 'X', '1', '0') == header.PixelFormat.FourCC))
            {
                // Buffer must be big enough for both headers and magic value
                if (size < (Unsafe.SizeOf<DDS.Header>() + sizeof (uint) + Unsafe.SizeOf<DDS.HeaderDXT10>()))
                    return false;

                var headerDX10 = *(DDS.HeaderDXT10*) ((byte*) headerPtr + sizeof (int) + Unsafe.SizeOf<DDS.Header>());
                convFlags |= ConversionFlags.DX10;

                description.ArraySize = headerDX10.ArraySize;
                if (description.ArraySize == 0)
                    throw new InvalidOperationException("Unexpected ArraySize == 0 from DDS HeaderDX10 ");

                description.Format = headerDX10.DXGIFormat;
                if (!description.Format.IsValid)
                    throw new InvalidOperationException("Invalid Format from DDS HeaderDX10 ");

                switch (headerDX10.ResourceDimension)
                {
                    case DDS.ResourceDimension.Texture1D:

                        // D3DX writes 1D textures with a fixed Height of 1
                        if ((header.Flags & DDS.HeaderFlags.Height) != 0 && header.Height != 1)
                            throw new InvalidOperationException("Unexpected Height != 1 from DDS HeaderDX10 ");

                        description.Width = header.Width;
                        description.Height = 1;
                        description.Depth = 1;
                        description.Dimension = TextureDimension.Texture1D;
                        break;

                    case DDS.ResourceDimension.Texture2D:
                        if ((headerDX10.MiscFlags & DDS.ResourceOptionFlags.TextureCube) != 0)
                        {

View on GitHub (pinned to 96fad776d2)