stride3d/stride · error · InvalidOperationException

Texture3D missing HeaderFlags.Volume from DDS HeaderDX10

Error message

Texture3D missing HeaderFlags.Volume from DDS HeaderDX10

What it means

In the DDS layout, volume (3D) textures in the legacy header must set the HeaderFlags.Volume bit. When the DX10 header says Texture3D but the legacy header lacks that flag, the file contradicts itself and DecodeDDSHeader throws, following DirectXTex validation.

Solutions

Regenerate the 3D texture DDS with a proper tool (texconv/image tool)
Set the HeaderFlags.Volume bit in the file's DX9 header if hand-fixing
Convert to a single 2D slice if 3D data isn't actually needed

Example fix

// before (DX9 header dwFlags)
dwFlags = HEIGHT|WIDTH|...            // missing VOLUME (0x00800000)
// after
dwFlags = HEIGHT|WIDTH|...|VOLUME     // 0x00800000 set

Defensive patterns

Strategy: validation

Validate before calling

// If DX10 ResourceDimension == Texture3D, require legacy VOLUME flag (0x00800000)
if (resourceDimension == 3 /*Texture3D*/) {
    uint flags = BitConverter.ToUInt32(ddsBytes, 8);
    if ((flags & 0x00800000) == 0) throw new InvalidOperationException("DDS Texture3D missing VOLUME flag in legacy header");
}

Try / catch

try { image = Image.Load(ddsBytes); } catch (InvalidOperationException ex) when (ex.Message.Contains("missing HeaderFlags.Volume")) { // regenerate or patch file
    throw new AssetLoadException("Malformed volume texture DDS; re-export with VOLUME flag", ex); }

Prevention

Generate 3D texture DDS with tools that set the VOLUME flag
Validate volume textures at import time
Don't manually convert array/2D DDS files to 3D by editing headers
Store source volume data in a neutral format and convert in the pipeline

When it happens

Trigger: Loading a DDS whose DX10 ResourceDimension is Texture3D while the DX9 header's dwFlags does not include DDS_HEADER_FLAGS_VOLUME (0x00800000).

Common situations: Files written by tools that set the DX10 dimension but not the legacy volume flag, hand-converted DDS files, corrupted downloads.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

                    case DDS.ResourceDimension.Texture2D:
                        if ((headerDX10.MiscFlags & DDS.ResourceOptionFlags.TextureCube) != 0)
                        {
                            description.ArraySize *= 6;
                            description.Dimension = TextureDimension.TextureCube;
                        }
                        else
                        {
                            description.Dimension = TextureDimension.Texture2D;
                        }

                        description.Width = header.Width;
                        description.Height = header.Height;
                        description.Depth = 1;
                        break;

                    case DDS.ResourceDimension.Texture3D:
                        if ((header.Flags & DDS.HeaderFlags.Volume) == 0)
                            throw new InvalidOperationException("Texture3D missing HeaderFlags.Volume from DDS HeaderDX10");

                        if (description.ArraySize > 1)
                            throw new InvalidOperationException("Unexpected ArraySize > 1 for Texture3D from DDS HeaderDX10");

                        description.Width = header.Width;
                        description.Height = header.Height;
                        description.Depth = header.Depth;
                        description.Dimension = TextureDimension.Texture3D;
                        break;

                    default:
                        throw new InvalidOperationException(string.Format("Unexpected dimension [{0}] from DDS HeaderDX10", headerDX10.ResourceDimension));
                }
            }
            else
            {
                description.ArraySize = 1;

View on GitHub (pinned to 96fad776d2)