stride3d/stride · error · InvalidOperationException

Unexpected ArraySize > 1 for Texture3D from DDS HeaderDX10

Error message

Unexpected ArraySize > 1 for Texture3D from DDS HeaderDX10

What it means

3D (volume) textures cannot be part of a texture array. If the DX10 header declares ArraySize > 1 together with ResourceDimension == Texture3D, DecodeDDSHeader rejects the file, matching DirectXTex's validation rules.

Solutions

Regenerate the DDS so 3D textures have ArraySize = 1
If an array is intended, export as Texture2D with array size instead
Patch ArraySize to 1 in the DX10 header if the data is genuinely a single volume

Example fix

// before (DX10 header)
ResourceDimension = Texture3D; ArraySize = 4
// after
ResourceDimension = Texture3D; ArraySize = 1

Defensive patterns

Strategy: validation

Validate before calling

// If DX10 ResourceDimension == Texture3D, require ArraySize == 1
if (resourceDimension == 3 /*Texture3D*/) {
    uint arraySize = BitConverter.ToUInt32(ddsBytes, 128 + 20);
    if (arraySize > 1) throw new InvalidOperationException("DDS Texture3D cannot have ArraySize > 1");
}

Try / catch

try { image = Image.Load(ddsBytes); } catch (InvalidOperationException ex) when (ex.Message.Contains("ArraySize > 1 for Texture3D")) { // regenerate as single volume or 2D array
    throw new AssetLoadException("DDS volume texture declares an array; re-export", ex); }

Prevention

Ensure exporters emit ArraySize = 1 for 3D textures
Use 2D texture arrays when array semantics are needed
Validate DX10 header fields in the asset import step
Pin to well-tested DDS tooling for volume textures

When it happens

Trigger: Loading a DDS with DX10 header where ResourceDimension is Texture3D and HeaderDXT10.ArraySize is greater than 1.

Common situations: Buggy exporters writing array counts for 3D textures, files converted from array textures to 3D without clearing ArraySize, corrupted files.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

                            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;

                if ((header.Flags & DDS.HeaderFlags.Volume) != 0)
                {
                    description.Width = header.Width;

View on GitHub (pinned to 96fad776d2)