MonoGame/MonoGame · error · ContentLoadException

Unsupported DDS_HEADER_DXT10 struct found

Error message

Unsupported DDS_HEADER_DXT10 struct found

What it means

Thrown by DdsLoader.Import when the pixel format flags indicate FourCC and the FourCC code is 'DX10' (0x30315844), signalling the presence of a DDS_HEADER_DXT10 extension struct. MonoGame's DDS importer does not support the DX10 header variant, which carries additional format metadata (e.g. BC4-BC7, array slices).

Source

Thrown at MonoGame.Framework.Content.Pipeline/DdsLoader.cs:275

            header.ddspf.dwRgbBitCount = reader.ReadUInt32();
            header.ddspf.dwRBitMask = reader.ReadUInt32();
            header.ddspf.dwGBitMask = reader.ReadUInt32();
            header.ddspf.dwBBitMask = reader.ReadUInt32();
            header.ddspf.dwABitMask = reader.ReadUInt32();
            // Continue reading DDS_HEADER
            header.dwCaps = (DdsCaps)reader.ReadUInt32();
            header.dwCaps2 = (DdsCaps2)reader.ReadUInt32();
            // dwCaps3 unused
            reader.ReadUInt32();
            // dwCaps4 unused
            reader.ReadUInt32();
            // dwReserved2 unused
            reader.ReadUInt32();

            // Check for the existence of the DDS_HEADER_DXT10 struct next
            if (header.ddspf.dwFlags == Ddpf.FourCC && header.ddspf.dwFourCC == FourCC.Dx10)
            {
                throw new ContentLoadException("Unsupported DDS_HEADER_DXT10 struct found");
            }

            var faceCount = 1;
            var mipMapCount = (int)(header.dwCaps.HasFlag(DdsCaps.MipMap) ? header.dwMipMapCount : 1);
            TextureContent output;
            if (header.dwCaps2.HasFlag(DdsCaps2.Cubemap))
            {
                if (!header.dwCaps2.HasFlag(DdsCaps2.CubemapAllFaces))
                    throw new ContentLoadException("Incomplete cubemap in DDS file");
                faceCount = 6;
                output = new TextureCubeContent() { Identity = identity };
            }
            else
            {
                output = new Texture2DContent() { Identity = identity };
            }

            var format = GetSurfaceFormat(ref header.ddspf, out bool rbSwap);

View on GitHub (pinned to 1d71bbd0ff)

Solutions

1. Re-export the DDS without a DX10 header using a legacy format: texconv -f DXT5 or -f DXT1 (these produce standard, non-DX10 headers).
2. Avoid BC4/BC5/BC6H/BC7 formats, which mandate DX10; use DXT1 or DXT5 instead.
3. If using texconv, ensure the output format maps to a non-DX10 FourCC.

Example fix

// before: texconv -f BC3_UNORM texture.png  (may still embed DX10 in some versions)
// after: explicitly target legacy DXT5
//   texconv -f DXT5 texture.png

// Avoid DX10 headers by exporting with legacy FourCC formats:
//   texconv -f DXT5 asset.png -o .
// To detect a DX10 header programmatically, read the pixel format:
// (simplified) if dwFourCC == 'DX10' (0x30315844) and DDPF.FourCC set -> reject.

try
{
    texture = DdsLoader.Import(filename, context);
}
catch (ContentLoadException ex) when (ex.Message.Contains("DDS_HEADER_DXT10"))
{
    logger.LogMessage($"{filename} uses a DX10 header (e.g. BC7); re-export as DXT1/DXT5.");
    throw;
}

When it happens

Trigger: Importing a DDS file authored with a DX10 header, commonly produced when exporting BC4, BC5, BC6H, BC7, or texture-array formats via modern texconv or DirectX tools.

Common situations: Using texconv defaults that emit DX10 headers; exporting BC7 (high-quality alpha) which requires the DX10 extension; artists using modern compression unaware MonoGame's importer lacks DX10 support.

Related errors

• Unsupported compression format DXT2
• Unsupported compression format DXT4
• Unsupported RGBA pixel format
• Unsupported RGB pixel format
• Unsupported pixel format

AI-assisted analysis of MonoGame/MonoGame@1d71bbd0ff (2026-08-13). Data as JSON: /api/errors/0e231254b3d00cd0. Report an issue: GitHub.