stride3d/stride · error · InvalidOperationException

Invalid Width/Height/Depth/ArraySize for Image 2D

Error message

Invalid Width/Height/Depth/ArraySize for Image 2D

What it means

For Texture2D and TextureCube images, Initialize requires Width > 0, Height > 0, Depth == 1, and ArraySize > 0. 2D images have no volumetric depth and must contain at least one array slice; anything else contradicts the declared dimension.

Solutions

1. Set Depth = 1 for Texture2D/TextureCube descriptions.
2. Set ArraySize >= 1 (6 * faceCount for cubes).
3. Ensure Width and Height are both positive.
4. Use TextureDimension.Texture3D if you genuinely need Depth > 1.

Example fix

// before
var desc = new ImageDescription { Dimension = TextureDimension.Texture2D, Width = w, Height = h, Depth = 4, ArraySize = 0 };
// after
var desc = new ImageDescription { Dimension = TextureDimension.Texture2D, Width = w, Height = h, Depth = 1, ArraySize = 1 };

bool is2D = desc.Dimension is TextureDimension.Texture2D or TextureDimension.TextureCube;
if (is2D && (desc.Width <= 0 || desc.Height <= 0 || desc.Depth != 1 || desc.ArraySize == 0))
    throw new ArgumentException("Texture2D/Cube requires Width>0, Height>0, Depth=1, ArraySize>=1.");

null

try { img = Image.New2D(width, height, mipCount, format, isArray, arraySize); }
catch (InvalidOperationException ex) when (ex.Message.Contains("for Image 2D"))
{
    logger.LogError("Invalid 2D image desc w={W} h={H} d={D} arr={A}", width, height, depth, arraySize);
    throw;
}

When it happens

Trigger: Creating an image with Dimension = TextureDimension.Texture2D (or TextureCube) where Depth != 1, ArraySize == 0, or Width/Height <= 0 — e.g. a default-initialized ImageDescription or a description zeroed by a failed load.

Common situations: Passing a 3D description with Depth > 1 while leaving Dimension as Texture2D; forgetting to set ArraySize when hand-building descriptions; image dimensions taken from a file header that failed to parse (width/height 0).

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

• Invalid Width/Height/Depth/ArraySize for Image 1D
• Unsupported DXGI Format
• Cannot specify custom stride with mipmaps
• TextureCube must have an arraysize = 6
• Invalid Width/Height/Depth/ArraySize for Image 3D

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

Appendix: source

Thrown at sources/engine/Stride.Foundation/Graphics/Image.cs:786

            if (rowStride > 0 && description.MipLevels != 1)
                throw new InvalidOperationException("Cannot specify custom stride with mipmaps");

            this.handle = handle;

            switch (description.Dimension)
            {
                case TextureDimension.Texture1D:
                    if (description.Width <= 0 || description.Height != 1 || description.Depth != 1 || description.ArraySize == 0)
                        throw new InvalidOperationException("Invalid Width/Height/Depth/ArraySize for Image 1D");

                    // Check that miplevels are fine
                    description.MipLevels = CalculateMipLevels(description.Width, 1, description.MipLevels);
                    break;

                case TextureDimension.Texture2D:
                case TextureDimension.TextureCube:
                    if (description.Width <= 0 || description.Height <= 0 || description.Depth != 1 || description.ArraySize == 0)
                        throw new InvalidOperationException("Invalid Width/Height/Depth/ArraySize for Image 2D");

                    if (description.Dimension == TextureDimension.TextureCube)
                    {
                        if ((description.ArraySize % 6) != 0)
                            throw new InvalidOperationException("TextureCube must have an arraysize = 6");
                    }

                    // Check that miplevels are fine
                    description.MipLevels = CalculateMipLevels(description.Width, description.Height, description.MipLevels);
                    break;

                case TextureDimension.Texture3D:
                    if (description.Width <= 0 || description.Height <= 0 || description.Depth <= 0 || description.ArraySize != 1)
                        throw new InvalidOperationException("Invalid Width/Height/Depth/ArraySize for Image 3D");

                    // Check that miplevels are fine
                    description.MipLevels = CalculateMipLevels(description.Width, description.Height, description.Depth, description.MipLevels);
                    break;

View on GitHub (pinned to 96fad776d2)